diff --git a/docs/_api_gen.rst b/docs/_api_gen.rst new file mode 100644 index 0000000000..f6aae4a9ab --- /dev/null +++ b/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 diff --git a/docs/conf.py b/docs/conf.py index 0d0cddeb09..1bc6421a12 100644 --- a/docs/conf.py +++ b/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 diff --git a/docs/index.md b/docs/index.md index dbf0348786..c38eeecc6a 100644 --- a/docs/index.md +++ b/docs/index.md @@ -23,14 +23,6 @@ FAQ :relative-docs: docs/ ``` -```{eval-rst} -.. autosummary:: - :toctree: _autosummary - :template: custom-module-template.rst - :recursive: - - baybe -``` ```{toctree} :maxdepth: 2 diff --git a/docs/scripts/build_documentation.py b/docs/scripts/build_documentation.py index 5b7b013a24..616427bce5 100644 --- a/docs/scripts/build_documentation.py +++ b/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")