Restructure and simplify API doc generation

* use flat structure for each module, do not nest classes in separate files * remove unused templates * fix whitespace problems This gives a considerable speed-up, achieving now normal durations around five minutes.
bayesflow-org · Jan 2, 2025 · 26209ef · 26209ef
1 parent d367cfd
commit 26209ef
Show file tree

Hide file tree

Showing 7 changed files with 97 additions and 158 deletions.
diff --git a/bayesflow/utils/serialization.py b/bayesflow/utils/serialization.py
@@ -66,7 +66,7 @@ def deserialize_value_or_type(config, name):
 
     See Also
     --------
-    `serialize_value_or_type`
+    serialize_value_or_type
     """
     updated_config = config.copy()
     if f"{PREFIX}{name}_type" in config:

diff --git a/docsrc/source/_templates/custom-base-template.rst b/docsrc/source/_templates/custom-base-template.rst
diff --git a/docsrc/source/_templates/custom-class-template.rst b/docsrc/source/_templates/custom-class-template.rst
diff --git a/docsrc/source/_templates/custom-module-template.rst b/docsrc/source/_templates/custom-module-template.rst
@@ -2,74 +2,61 @@
 
 .. automodule:: {{ fullname }}
 
-   {% block attributes %}
-   {% if attributes %}
-   .. rubric:: Module Attributes
-
-   .. autosummary::
-      :toctree:                                          
-   {% for item in attributes %}
-      {{ item }}
-   {%- endfor %}
-   {% endif %}
-   {% endblock %}
-
-   {% block functions %}
-   {% if functions %}
-   .. rubric:: {{ _('Functions') }}
-
-   .. autosummary::
-      :toctree:                                          
-   {% for item in functions %}
-      {{ item }}
-   {%- endfor %}
-   {% endif %}
-   {% endblock %}
-
-   {% block classes %}
-   {% if classes %}
-   .. rubric:: {{ _('Classes') }}
-
-   .. autosummary::
-      :toctree:                                          
-      :template: custom-class-template.rst               
-   {% for item in classes %}
-      {{ item }}
-   {%- endfor %}
-   {% endif %}
-   {% endblock %}
-
-   {% block exceptions %}
-   {% if exceptions %}
-   .. rubric:: {{ _('Exceptions') }}
-
-   .. autosummary::
-      :toctree:                                          
-   {% for item in exceptions %}
-      {{ item }}
-   {%- endfor %}
-   {% endif %}
-   {% endblock %}
-
-{% block modules %}
-{% if modules %}
-.. rubric:: Modules
-
-.. autosummary::
-   :toctree:
-   :template: custom-module-template.rst                 
-   :recursive:
-{% for item in modules %}
-   {{ item }}
-{%- endfor %}
-
-.. rubric:: Submodules
-.. toctree::
-    :maxdepth: 1
-    :titlesonly:
-{% for item in modules %}
-   {{ item }}
-{%- endfor %}
-
-{% endif %}
-{% endblock %}
+  {% block attributes %}
+  {% if attributes %}
+  .. rubric:: Module Attributes
+
+  .. autosummary::
+  {% for item in attributes %}
+    {{ item }}
+  {%- endfor %}
+  {% endif %}
+  {% endblock %}
+
+  {% block functions %}
+  {% if functions %}
+  .. rubric:: {{ _('Functions') }}
+
+  .. autosummary::
+  {% for item in functions %}
+    {{ item }}
+  {%- endfor %}
+  {% endif %}
+  {% endblock %}
+
+  {% block classes %}
+  {% if classes %}
+  .. rubric:: {{ _('Classes') }}
+
+  .. autosummary::
+  {% for item in classes %}
+    {{ item }}
+  {%- endfor %}
+  {% endif %}
+  {% endblock %}
+
+  {% block exceptions %}
+  {% if exceptions %}
+  .. rubric:: {{ _('Exceptions') }}
+
+  .. autosummary::
+  {% for item in exceptions %}
+    {{ item }}
+  {%- endfor %}
+  {% endif %}
+  {% endblock %}
+
+  {% block modules %}
+  {% if modules %}
+  .. rubric:: Modules
+
+  .. autosummary::
+    :toctree:
+    :template: custom-module-template.rst
+    :recursive:
+  {% for item in modules %}
+    {{ item }}
+  {%- endfor %}
+
+  {% endif %}
+  {% endblock %}
diff --git a/docsrc/source/api/bayesflow.rst b/docsrc/source/api/bayesflow.rst
@@ -11,35 +11,15 @@ Autosummary
     :template: custom-module-template.rst
     :recursive:
 
-   bayesflow.adapters
-   bayesflow.approximators
-   bayesflow.benchmarks
-   bayesflow.datasets
-   bayesflow.diagnostics
-   bayesflow.distributions
-   bayesflow.metrics
-   bayesflow.networks
-   bayesflow.simulators
-   bayesflow.types
-   bayesflow.utils
-   bayesflow.workflows
-
-
-Submodules
-----------
-
-.. toctree::
-   :maxdepth: 2
-
-   bayesflow.adapters
-   bayesflow.approximators
-   bayesflow.benchmarks
-   bayesflow.datasets
-   bayesflow.diagnostics
-   bayesflow.distributions
-   bayesflow.metrics
-   bayesflow.networks
-   bayesflow.simulators
-   bayesflow.types
-   bayesflow.utils
-   bayesflow.workflows
+    bayesflow.adapters
+    bayesflow.approximators
+    bayesflow.benchmarks
+    bayesflow.datasets
+    bayesflow.diagnostics
+    bayesflow.distributions
+    bayesflow.metrics
+    bayesflow.networks
+    bayesflow.simulators
+    bayesflow.types
+    bayesflow.utils
+    bayesflow.workflows
diff --git a/docsrc/source/conf.py b/docsrc/source/conf.py
@@ -28,7 +28,7 @@
 
 project = "BayesFlow"
 author = "The BayesFlow authors"
-copyright = "2023, BayesFlow authors (lead maintainer: Stefan T. Radev)"
+copyright = "2023-2025, BayesFlow authors (lead maintainer: Stefan T. Radev)"
 
 
 # -- General configuration ---------------------------------------------------
@@ -61,13 +61,6 @@
     "html_image",
 ]
 myst_url_schemes = ["http", "https", "mailto"]
-autodoc_default_options = {
-    "members": "var1, var2",
-    "special-members": "__call__,__init__",
-    "undoc-members": True,
-    "exclude-members": "__weakref__",
-    "member-order": "bysource",
-}
 
 # Define shorthand for external links:
 extlinks = {
@@ -83,7 +76,23 @@
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = []
+
+# Options for autodoc and autosummary
+autodoc_default_options = {
+    "members": True,
+    "undoc-members": True,
+    "imported-members": True,
+    "inherited-members": True,
+    "show-inheritance": True,
+    "special-members": "__call__",
+    "memberorder": "bysource",
+}
+# do not ignore __all__, use it to determine public members
+autosummary_ignore_module_all = False
+# include imported members in autosummary
 autosummary_imported_members = True
+# selects content to insert into the main body of an autoclass directive.
+autoclass_content = "both"
 
 
 # -- Options for HTML output -------------------------------------------------

diff --git a/docsrc/source/index.rst b/docsrc/source/index.rst
@@ -113,12 +113,12 @@ Indices
 
 
 .. toctree::
-   :maxdepth: 0
-   :titlesonly:
-   :hidden:
-
-   self
-   examples
-   api/bayesflow
-   contributing
-   about
+    :maxdepth: 0
+    :titlesonly:
+    :hidden:
+
+    self
+    examples
+    api/bayesflow
+    contributing
+    about