Add plugin

This is mostly based on the extension submitted as a pull request for
Sphinx [1].

[1] sphinx-doc/sphinx#4101

Signed-off-by: Stephen Finucane <[email protected]>

Author: stephenfin

requirements.txt

@@ -1 +1,2 @@
 pbr
+Sphinx>=1.6.0

sphinxcontrib/apidoc/__init__.py

@@ -10,6 +10,23 @@
 
 import pbr.version
 
+from sphinxcontrib.apidoc import ext
 
-__version__ = pbr.version.VersionInfo(
-    'apidoc').version_string()
+__version__ = pbr.version.VersionInfo('apidoc').version_string()
+
+if False:
+    # For type annotation
+    from typing import Any, Dict  # noqa
+    from sphinx.application import Sphinx  # noqa
+
+
+def setup(app):
+    # type: (Sphinx) -> Dict[unicode, Any]
+    app.setup_extension('sphinx.ext.autodoc')  # We need autodoc to function
+
+    app.connect('builder-inited', ext.builder_inited)
+    app.add_config_value('apidoc_module_dir', None, 'env', [str])
+    app.add_config_value('apidoc_output_dir', 'api', 'env', [str])
+    app.add_config_value('apidoc_excluded_modules', [], 'env', [[str]])
+
+    return {'version': __version__, 'parallel_read_safe': True}

sphinxcontrib/apidoc/ext.py

@@ -0,0 +1,51 @@
+"""
+    sphinxcontrib.apidoc.ext
+    ~~~~~~~~~~~~~~~~~~~~~~~~
+
+    A Sphinx extension for running 'sphinx-apidoc' on each build.
+
+    :copyright: Copyright 2018 by Stephen Finucane <[email protected]>
+    :license: BSD, see LICENSE for details.
+"""
+
+from os import path
+
+from sphinx.util import logging
+
+try:
+    from sphinx.ext import apidoc  # Sphinx >= 1.7
+except ImportError:
+    from sphinx import apidoc  # Sphinx < 1.7
+
+if False:
+    # For type annotation
+    from sphinx.application import Sphinx  # noqa
+
+logger = logging.getLogger(__name__)
+
+
+def builder_inited(app):
+    # type: (Sphinx) -> None
+    module_dir = app.config.apidoc_module_dir
+    output_dir = path.join(app.srcdir, app.config.apidoc_output_dir)
+    excludes = app.config.apidoc_excluded_modules
+
+    if not module_dir:
+        logger.warning("No 'apidoc_module_dir' specified; skipping API doc "
+                       "generation")
+        return
+
+    # if the path is relative, make it relative to the 'conf.py' directory
+    if not path.isabs(module_dir):
+        module_dir = path.abspath(path.join(app.srcdir, module_dir))
+
+    excludes = [path.abspath(path.join(module_dir, exc)) for exc in excludes]
+
+    # refactor this module so that we can call 'recurse_tree' like a sane
+    # person - at present there is way too much passing around of the
+    # 'optparse.Value' instance returned by 'optparse.parse_args'
+    cmd = ['--force', '-o', output_dir, module_dir]
+    if excludes:
+        cmd += excludes
+
+    apidoc.main(cmd)

sphinxcontrib/apidoc/tests/conftest.py

@@ -6,4 +6,16 @@
     :license: BSD, see LICENSE for details.
 """
 
+import os
+
+import pytest
+from sphinx.testing.path import path
+
 pytest_plugins = 'sphinx.testing.fixtures'
+
+collect_ignore = ['roots']
+
+
+@pytest.fixture(scope='session')
+def rootdir():
+    return path(os.path.dirname(__file__) or '.').abspath() / 'roots'

sphinxcontrib/apidoc/tests/roots/test-apidoc/apidoc_dummy_module.py

@@ -0,0 +1,9 @@
+from os import *  # noqa
+
+
+class Foo:
+    def __init__(self):
+        pass
+
+    def bar(self):
+        pass

sphinxcontrib/apidoc/tests/roots/test-apidoc/conf.py

@@ -0,0 +1,12 @@
+# -*- coding: utf-8 -*-
+
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath('./'))
+
+extensions = ['sphinxcontrib.apidoc']
+master_doc = 'index'
+
+apidoc_module_dir = '.'
+apidoc_excluded_modules = ['conf.py']

sphinxcontrib/apidoc/tests/roots/test-apidoc/index.rst

@@ -0,0 +1,6 @@
+apidoc
+======
+
+.. toctree::
+
+   api/modules

sphinxcontrib/apidoc/tests/test_ext.py

@@ -0,0 +1,21 @@
+# -*- coding: utf-8 -*-
+"""
+    test_apidoc
+    ~~~~~~~~~~~
+
+    Test the sphinxcontrib.apidoc module.
+
+    :copyright: Copyright 2018 by Stephen Finucane <[email protected]>.
+    :license: BSD, see LICENSE for details.
+"""
+
+import pytest
+
+
+@pytest.mark.sphinx('html', testroot='apidoc')
+def test_apidoc_extension(app, status, warning):
+    app.builder.build_all()
+    assert (app.outdir / 'api').isdir()
+    assert (app.outdir / 'api' / 'modules.html').exists()
+    assert (app.outdir / 'api' / 'apidoc_dummy_module.html').exists()
+    assert not (app.outdir / 'api' / 'conf.html').exists()