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. PS. My primary goal from the start was to reuse a real C language parser instead of writing yet another regexp based parser in the style of kernel-doc the perl script. The project would never have seen the light of day otherwise. I looked into gcc, sparse, and some other parsers before settling on python-clang. The codebase is just a few hundred lines of python. Which brings us to the secondary goal of minimalism. There's already Doxygen, with Breathe to bridge the gap to Sphinx, but they're huge projects with creeping featurism. I don't want any of that. I offload as much as possible to python-clang and Sphinx, with minimal glue in between. Granted, Hawkmoth is nowhere near complete, but I aim for the sweet spot of enough features with a minimal codebase, sane defaults with minimal configuration, good enough for documenting most C projects. I do understand some folks don't really appreciate the clang dependency. Folks like other compiler developers. ;) BR, Jani. > > [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 -- 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
