diff options
| author | Luc Van Oostenryck <luc.vanoostenryck@gmail.com> | 2018-05-11 11:32:01 +0200 |
|---|---|---|
| committer | Luc Van Oostenryck <luc.vanoostenryck@gmail.com> | 2018-05-21 02:49:44 +0200 |
| commit | f647b26c75beb08bb51d308f9922776d4de091e9 (patch) | |
| tree | f444516b65ab77a1ba5f43ae425aff56d9586810 /Documentation/sphinx | |
| parent | 2d70615dc7815cab2d3b28fc3a8ca29bbc19a834 (diff) | |
| download | sparse-dev-f647b26c75beb08bb51d308f9922776d4de091e9.tar.gz | |
autodoc: add a sphinx c:autodoc directive for the extracted doc
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.org>
Signed-off-by: Luc Van Oostenryck <luc.vanoostenryck@gmail.com>
Diffstat (limited to 'Documentation/sphinx')
| -rwxr-xr-x | Documentation/sphinx/cdoc.py | 49 |
1 files changed, 49 insertions, 0 deletions
diff --git a/Documentation/sphinx/cdoc.py b/Documentation/sphinx/cdoc.py index 1953f1f2..56d31cb1 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 +// """ @@ -240,4 +245,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': '0.9', + 'parallel_read_safe': True, + } + # vim: tabstop=4 |