Automatically run sphinx-apidoc during documentation build (#348)

* Automatically run sphinx-apidoc during documentation build

* Make isort and black happy

* Clean up the code, add a docstring

* Remove an unnecessary 'map' call

* Update docs/source/conf.py

Co-authored-by: Poruri Sai Rahul <rporuri@enthought.com>

* Hook into config-inited instead of builder-inited

Co-authored-by: Poruri Sai Rahul <rporuri@enthought.com>

.github/workflows/build-docs.yml

@@ -27,7 +27,6 @@ jobs:
         python -m pip install .
     - name: Build HTML documentation with Sphinx
       run: |
-        python -m sphinx.ext.apidoc -e -T -o docs/source/api -t docs/source/api/templates traits_futures */tests
         cd docs
         python -m sphinx -b html -d doctrees source build
     - name: Configure Git

.github/workflows/test-docs.yml

@@ -25,9 +25,6 @@ jobs:
     - name: Install local package
       run: |
         python -m pip install .
-    - name: Autogenerate API documentation
-      run: |
-        python -m sphinx.ext.apidoc -e -T -o docs/source/api -t docs/source/api/templates traits_futures */tests
     - name: Build HTML documentation
       run: |
         cd docs

ci/__main__.py

@@ -226,23 +226,6 @@ def doc(edm, python_version, toolkit):
     """
     pyenv = _get_devenv(edm, python_version, toolkit)
 
-    # Use sphinx-apidoc to build API documentation.
-    docs_source_api = "docs/source/api"
-    template_dir = "docs/source/api/templates/"
-    apidoc_command = [
-        "-m",
-        "sphinx.ext.apidoc",
-        "--separate",
-        "--no-toc",
-        "-o",
-        docs_source_api,
-        "-t",
-        template_dir,
-        "traits_futures",
-        "*/tests",
-    ]
-    pyenv.python(apidoc_command)
-
     # Be nitpicky. This detects missing class references.
     sphinx_options = ["-n"]
 

docs/source/conf.py

@@ -202,3 +202,43 @@
     "traits": ("https://docs.enthought.com/traits", None),
     "traitsui": ("https://docs.enthought.com/traitsui", None),
 }
+
+
+def run_apidoc(app, config):
+    """
+    Hook to generate API documentation via sphinx-apidoc
+
+    Parameters
+    ----------
+    app : the Sphinx application
+    config : the Sphinx configuration
+    """
+    import pathlib
+
+    import sphinx.ext.apidoc
+
+    source_dir = pathlib.Path(__file__).parent
+    project_root = source_dir.parent.parent
+    target_dir = project_root / "traits_futures"
+
+    exclude_patterns = [
+        target_dir / "tests" / "*.py",
+        target_dir / "*" / "tests" / "*.py",
+    ]
+
+    args = [
+        "--separate",
+        "--no-toc",
+        "--templatedir",
+        source_dir / "api" / "templates",
+        "-o",
+        source_dir / "api",
+        target_dir,
+        *exclude_patterns,
+    ]
+
+    sphinx.ext.apidoc.main([str(arg) for arg in args])
+
+
+def setup(app):
+    app.connect("config-inited", run_apidoc)