docs: automate API docs

Automatically create pages in the API docs section using sphinx-autodoc. This is added as an event handler in conf.py.
python-semantic-release · Apr 8, 2020 · 7d4fea2 · 7d4fea2
1 parent af24bc2
commit 7d4fea2
Show file tree

Hide file tree

Showing 6 changed files with 25 additions and 107 deletions.
diff --git a/.gitignore b/.gitignore
@@ -59,6 +59,7 @@ coverage.xml
 
 # Sphinx documentation
 docs/_build/
+docs/api/
 
 # PyBuilder
 target/

diff --git a/docs/api/modules.rst b/docs/api/modules.rst
diff --git a/docs/api/semantic_release.history.rst b/docs/api/semantic_release.history.rst
diff --git a/docs/api/semantic_release.rst b/docs/api/semantic_release.rst
diff --git a/docs/conf.py b/docs/conf.py
@@ -35,6 +35,29 @@
 htmlhelp_basename = 'python-semantic-releasedoc'
 
 
+# -- Automatically run sphinx-apidoc --------------------------------------
+
+def run_apidoc(_):
+    from sphinx import apidoc
+
+    docs_path = os.path.dirname(__file__)
+    apidoc_path = os.path.join(docs_path, 'api')
+    module_path = os.path.join(docs_path, '..', 'semantic_release')
+
+    apidoc.main([
+        '--force',
+        '--module-first',
+        '--separate',
+        '-d', '3',
+        '-o', apidoc_path,
+        module_path
+    ])
+
+
+def setup(app):
+    app.connect('builder-inited', run_apidoc)
+
+
 # -- Options for LaTeX output ---------------------------------------------
 latex_documents = [
     ('index', 'python-semantic-release.tex', u'python-semantic-release Documentation',

diff --git a/docs/index.rst b/docs/index.rst
@@ -55,6 +55,6 @@ Documentation Contents
    Automatic releases <automatic-releases/index>
    Configuration <configuration>
    Environment Variables <envvars>
-   API docs <api/semantic_release>
+   API docs <api/modules>
    Troubleshooting <troubleshooting>
    Contributors <contributors>