On Mon, 14 May 2018, Luc Van Oostenryck <luc.vanoostenryck@xxxxxxxxx> wrote: > 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> That would be Jani Nikula <jani@xxxxxxxxxx>. It's my own private pet project. But thanks for the acknowledgement. BR, Jani. > 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 -- Jani Nikula, Intel Open Source Technology Center -- 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
