docs: move sphinx-apidoc generation out of conf.py

docs/_api_gen.rst

@@ -0,0 +1,11 @@
+:orphan:
+
+.. This file exists solely to trigger autosummary stub generation.
+.. It is marked as :orphan: so it does not appear in any toctree.
+
+.. autosummary::
+   :toctree: _autosummary
+   :template: custom-module-template.rst
+   :recursive:
+
+   baybe

docs/conf.py

@@ -4,9 +4,6 @@
 #
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
-import os
-import shutil
-
 from gpytorch.kernels import Kernel as GPyTorchKernel
 from gpytorch.likelihoods import Likelihood as GPyTorchLikelihood
 from gpytorch.means import Mean as GPyTorchMean
@@ -48,16 +45,6 @@
 
 # >>>>>>>>>> NOTE END <<<<<<<<<<
 
-# -- Path setup --------------------------------------------------------------
-
-__location__ = os.path.dirname(__file__)
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-# Seems to be not necessary at the moment
-# sys.path.insert(0, os.path.join(__location__, "../examples"))
-
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
@@ -66,48 +53,6 @@
 author = "Merck KGaA, Darmstadt, Germany"
 
 
-# -- Run sphinx-apidoc -------------------------------------------------------
-# This hack is necessary since RTD does not issue `sphinx-apidoc` before running
-# `sphinx-build -b html . _build/html`. See Issue:
-# https://github.com/readthedocs/readthedocs.org/issues/1139
-# DON'T FORGET: Check the box "Install your project inside a virtualenv using
-# setup.py install" in the RTD Advanced Settings.
-# Additionally it helps us to avoid running apidoc manually
-
-try:  # for Sphinx >= 1.7
-    from sphinx.ext import apidoc
-except ImportError:
-    from sphinx import apidoc
-
-output_dir = os.path.join(__location__, "sdk")
-baybe_module_dir = os.path.join(__location__, "../baybe")
-try:
-    shutil.rmtree(output_dir)
-except FileNotFoundError:
-    pass
-
-try:
-    args = [
-        "--implicit-namespaces",
-        "-M",
-        "-T",
-        "-e",
-        "-f",
-        "-o",
-        output_dir,
-    ]
-
-    apidoc.main(
-        [
-            *args,
-            baybe_module_dir,
-            baybe_module_dir + "/__init__.py",
-        ]
-    )
-except Exception as e:
-    print(f"Running `sphinx-apidoc` failed!\n{e}")
-
-
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 

docs/index.md

@@ -23,14 +23,6 @@ FAQ <faq>
 :relative-docs: docs/
 ```
 
-```{eval-rst}
-.. autosummary::
-   :toctree: _autosummary
-   :template: custom-module-template.rst
-   :recursive:
-
-   baybe
-```
 
 ```{toctree}
 :maxdepth: 2

docs/scripts/build_documentation.py

@@ -3,6 +3,7 @@
 import argparse
 import os
 import pathlib
+import shutil
 from subprocess import check_call, run
 
 from build_examples import build_examples
@@ -42,6 +43,32 @@
 FORCE = args.force
 
 
+def _run_apidoc() -> None:
+    """Generate API reference RST stubs via sphinx-apidoc."""
+    from sphinx.ext import apidoc
+
+    output_dir = pathlib.Path("docs/sdk")
+    module_dir = pathlib.Path("baybe")
+
+    # Remove previously generated stubs to ensure a clean state
+    if output_dir.is_dir():
+        shutil.rmtree(output_dir)
+
+    apidoc.main(
+        [
+            "--implicit-namespaces",
+            "-M",
+            "-T",
+            "-e",
+            "-f",
+            "-o",
+            str(output_dir),
+            str(module_dir),
+            str(module_dir / "__init__.py"),
+        ]
+    )
+
+
 def build_documentation(
     run_examples: bool = False,
     full_rebuild: bool = False,
@@ -89,6 +116,9 @@ def build_documentation(
             remove_dir=examples_exist,
         )
 
+    # Generate API reference stubs via sphinx-apidoc
+    _run_apidoc()
+
     # Directory where the documentation is build.
     build_dir = pathlib.Path("docs/build")