@@ -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
@@ -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
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> --- Documentation/conf.py | 10 +++++--- Documentation/sphinx/cdoc.py | 49 ++++++++++++++++++++++++++++++++++++ 2 files changed, 56 insertions(+), 3 deletions(-)