chg: dev: As a directive we cannot add new generated files so the development approach changed.

Now all modules to build documentation for will be listed in the conf.py.

Author: carlos-jenkins

.gitignore

@@ -9,7 +9,9 @@ build/*
 
 # Sphinx
 doc/_build/*
-doc/fixme/*
+
+# Sphinx autoapi
+doc/autoapi/*
 
 # Tox
 .tox/*

doc/conf.py

@@ -311,6 +311,9 @@
 # If true, do not generate a @detailmenu in the "Top" node's menu.
 # texinfo_no_detailmenu = False
 
+# autoapi configuration
+autoapi_modules = {'autoapi': None}
+
 # Configure PlantUML
 plantuml = 'java -jar ' + join(dirname(abspath(__name__)), 'plantuml.8030.jar')
 plantuml_output_format = 'svg'

doc/index.rst

@@ -2,7 +2,7 @@
    :hidden:
 
    developer
-   reference
+   autoapi/autoapi
 
 =======
 autoapi
@@ -12,14 +12,15 @@ autoapi
 
    .. image:: _static/images/logo.png
 
-Automatic API reference documentation generation for Sphinx inspired by Doxygen
+Automatic API reference documentation generation for Sphinx inspired by
+Doxygen.
 
 
 Documentation
 =============
 
 - :doc:`Developer Guide. <developer>`
-- :doc:`Internal Documentation Reference. <reference>`
+- :doc:`Internal Documentation Reference. <autoapi/autoapi>`
 
 
 Development

doc/reference.rst

@@ -22,113 +22,105 @@
 from __future__ import unicode_literals, absolute_import
 from __future__ import print_function, division
 
-from os.path import join, dirname, abspath
-from traceback import print_exc
+from os.path import join, dirname, abspath, exists
 
 from jinja2.sandbox import SandboxedEnvironment
-
-from docutils.parsers.rst import Directive
-from docutils.statemachine import ViewList
 from sphinx.util.osutil import ensuredir
 from sphinx.jinja2glue import BuiltinTemplateLoader
 
 from . import __version__
 from .apinode import APINode
 
 
-class AutoAPI(Directive):
+def get_template_env(app):
     """
-    Autoapi directive.
+    Get the template environment.
 
-    This directive will perform the following steps:
+    .. note::
 
-    - Build a :class:`autoapi.apinode.APINode` tree with the module name
-      specified as argument.
-    - Render the Jinja2 template with the root node and append the result as
-      content for this directive.
-    - Traverse the tree and for each node, except for leaf nodes without public
-      API, render the Jinja2 template and write the result as a new source
-      file.
+       Template should be loaded as a package_data using
+       :py:function:`pkgutil.get_data`, but because we want the user to
+       override the default template we need to hook it to the Sphinx loader,
+       and thus a file system approach is required as it is implemented like
+       that.
     """
-    required_arguments = 1
-    optional_arguments = 0
-    final_argument_whitespace = False
-    has_content = True
-    option_spec = {}
-
-    def autoapi_build(self, tree):
-        """
-        """
-        env = self.state.document.settings.env
-
-        # DEBUG
-        print('=' * 79)
-        print(env.config.source_suffix)
-        print(env.srcdir)
-        print(env.doctreedir)
-        print(env.found_docs)
-        print('=' * 79)
+    template_dir = [join(dirname(abspath(__file__)), 'template')]
+    template_loader = BuiltinTemplateLoader()
+    template_loader.init(app.builder, dirs=template_dir)
+    template_env = SandboxedEnvironment(loader=template_loader)
+    return template_env
 
-        # Get template
-        # Note: Template should be loaded as a package_data using
-        # pkgutil.get_data(), but because we want the user to override the
-        # default template we need to hook it to the Sphinx loader, and thus
-        # a file system approach is required as it is implemented like that.
-        template_dir = [join(dirname(abspath(__file__)), 'template')]
-        template_loader = BuiltinTemplateLoader()
-        template_loader.init(env.app.builder, dirs=template_dir)
-        template_env = SandboxedEnvironment(loader=template_loader)
-        template = template_env.get_template('module.rst')
-
-        # Render root and append it to current node content
-        autodoc = template.render(node=tree)
-        self.content.extend(
-            ViewList(initlist=autodoc.splitlines(), source=tree.name)
-        )
-
-        # Render all remaining nodes as separated documents
-        gen_dir = join(env.srcdir, 'fixme')
-        ensuredir(gen_dir)
-
-        for name, node in tree.directory.items():
-
-            # Ignore leaf nodes with public API
-            # Non-leaf nodes without public API are required to be rendered
-            # in order to have an index of their subnodes.
-            if node.is_leaf and not node.has_public_api():
-                continue
 
-            out_file = join(gen_dir, name + env.config.source_suffix[0])
-            with open(out_file, 'w') as fd:
-                fd.write(template.render(node=node))
+def builder_inited(app):
+    """
+    autoapi Sphinx extension hook for the ``builder-inited`` event.
 
-    def run(self):
-        # Get name of the module that is directive argument
-        module = self.arguments[0]
+    This hook will read the configuration value ``autoapi_modules`` and render
+    the modules described in it.
+    """
+    # Get modules to build documentation for
+    modules = app.config.autoapi_modules
+    if not modules:
+        return
 
-        try:
-            # Build module tree
-            tree = APINode(module)
+    # Get template environment
+    template_env = get_template_env(app)
 
-            # Generate content
-            self.autoapi_build(tree)
+    for module, options in modules.items():
 
-        except Exception as e:
-            # Create a warning if the process failed
-            print_exc()
-            msg = 'Unable to build autoapi for {}: {}'.format(module, str(e))
-            return [
-                self.state.document.reporter.warning(msg, line=self.lineno)
-            ]
+        # Get options
+        defaults = {
+            'override': True,
+            'template': 'module.rst',
+            'output': module
+        }
+        if options:
+            defaults.update(options)
 
-        return []
+        # Get template
+        template = template_env.get_template(defaults['template'])
+
+        # Build API tree
+        tree = APINode(module)
+
+        # Gather nodes to document
+        # Ignore leaf nodes without public API
+        # Non-leaf nodes without public API are required to be rendered
+        # in order to have an index of their subnodes.
+        nodes = [
+            (name, node) for name, node in tree.directory.items()
+            if node.has_public_api() or not node.is_leaf()
+        ]
+        if not nodes:
+            continue
+
+        # Define output directory
+        out_dir = join(app.env.srcdir, defaults['output'])
+        ensuredir(out_dir)
+
+        # Iterate nodes and render them
+        for name, node in nodes:
+            out_file = join(out_dir, name + app.config.source_suffix[0])
+
+            # Skip file if it override is off and it exists
+            if not defaults['override'] and exists(out_file):
+                continue
+
+            with open(out_file, 'w') as fd:
+                fd.write(template.render(node=node))
 
 
 def setup(app):
+    """
+    autoapi Sphinx extension setup.
+
+    See http://sphinx-doc.org/extdev/tutorial.html#the-setup-function
+    """
     # autodoc is required
     app.setup_extension('sphinx.ext.autodoc')
-    app.add_directive('autoapi', AutoAPI)
-    return {'version': __version__, 'parallel_read_safe': True}
+    app.add_config_value('autoapi_modules', {}, True)
+    app.connect(b'builder-inited', builder_inited)
+    return {'version': __version__}
 
 
-__all__ = ['AutoAPI']
+__all__ = ['builder_inited', 'setup']