Add a sphinx extension for the c:autodoc directive which will extract the doc and inject it into the document tree. This part is based on Jani Nikula's project: hawkmoth [1] which has exactly the same goal as this series but which use clang to parse the C code and extract the bloc-coments. [1] https://github.com/jnikula/hawkmoth Based-on-work-by: Jani Nikula <jani@xxxxxxxxxx> Signed-off-by: Luc Van Oostenryck <luc.vanoostenryck@xxxxxxxxx> --- Documentation/conf.py | 10 +++++--- Documentation/sphinx/cdoc.py | 49 ++++++++++++++++++++++++++++++++++++ 2 files changed, 56 insertions(+), 3 deletions(-) diff --git a/Documentation/conf.py b/Documentation/conf.py index 24f0f89ab..e86be1a0a 100644 --- a/Documentation/conf.py +++ b/Documentation/conf.py @@ -21,14 +21,14 @@ import datetime # -- General configuration ------------------------------------------------ -# If your documentation needs a minimal Sphinx version, state it here. -# -# needs_sphinx = '1.0' +needs_sphinx = '1.3' # Add any Sphinx extension module names here, as strings. They can be # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. +sys.path.insert(0, os.path.abspath('sphinx')) extensions = [ + 'cdoc' ] # support .md with python2 & python3 @@ -88,6 +88,10 @@ pygments_style = 'sphinx' # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = True +# -- Options for cdoc extension ------------------------------------------- + +cdoc_srcdir = '..' + # -- Options for HTML output ---------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for diff --git a/Documentation/sphinx/cdoc.py b/Documentation/sphinx/cdoc.py index d2e569739..7137b2a67 100755 --- a/Documentation/sphinx/cdoc.py +++ b/Documentation/sphinx/cdoc.py @@ -39,6 +39,11 @@ // Some future versions will also allow to document structures, unions, // enums, typedefs and variables. // +// This documentation can be extracted into a .rst document by using +// the *autodoc* directive:: +// +// .. c:autodoc:: file.c +// """ @@ -243,4 +248,48 @@ if __name__ == '__main__': dump_doc(extract(sys.stdin, '<stdin>')) + +from sphinx.ext.autodoc import AutodocReporter +import docutils +import os +class CDocDirective(docutils.parsers.rst.Directive): + required_argument = 1 + optional_arguments = 1 + has_content = False + option_spec = { + } + + def run(self): + env = self.state.document.settings.env + filename = os.path.join(env.config.cdoc_srcdir, self.arguments[0]) + env.note_dependency(os.path.abspath(filename)) + + ## create a (view) list from the extracted doc + lst = docutils.statemachine.ViewList() + f = open(filename, 'r') + for (lineno, lines) in extract(f, filename): + for l in lines.split('\n'): + lst.append(l.expandtabs(8), filename, lineno) + lineno += 1 + + ## let parse this new reST content + memo = self.state.memo + save = memo.reporter, memo.title_styles, memo.section_level + memo.reporter = AutodocReporter(lst, memo.reporter) + node = docutils.nodes.section() + try: + self.state.nested_parse(lst, 0, node, match_titles=1) + finally: + memo.reporter, memo.title_styles, memo.section_level = save + return node.children + +def setup(app): + app.add_config_value('cdoc_srcdir', None, 'env') + app.add_directive_to_domain('c', 'autodoc', CDocDirective) + + return { + 'version': __version__, + 'parallel_read_safe': True, + } + # vim: tabstop=4 -- 2.17.0 -- To unsubscribe from this list: send the line "unsubscribe linux-sparse" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
