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.nikula@xxxxxxxxx> Signed-off-by: Luc Van Oostenryck <luc.vanoostenryck@xxxxxxxxx> --- Documentation/conf.py | 10 +++++--- Documentation/sphinx/cdoc.py | 44 ++++++++++++++++++++++++++++++++++++ 2 files changed, 51 insertions(+), 3 deletions(-) diff --git a/Documentation/conf.py b/Documentation/conf.py index 45e52352a..474918116 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 @@ -85,6 +85,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 29690f6f0..b0cad851f 100755 --- a/Documentation/sphinx/cdoc.py +++ b/Documentation/sphinx/cdoc.py @@ -213,4 +213,48 @@ if __name__ == '__main__': dump_doc(sys.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): + 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
