DOC: Auto-generate full API docs (#1505)

* DOC: Use auto-summary to generate full API docs

Use custom template to prevent every class and function from getting its
own page.

* MNT: Ignore generated API docs

* DOC: Update docstrings due to sphinx complaints

* DOC: Add intersphinx

Author: effigies

tools/schemacode/bidsschematools/tests/test_make_testdata.py

@@ -24,12 +24,14 @@ def test_make_archive(bids_examples, bids_error_examples):
 
     Notes
     -----
-    * Due to intricacies arising from:
-        (1) fixtures not working outside of pytest
-        (2) implicit teardown leveraging tempdata removal (while held open by yield)
-        (3) wrappers evaluating the yield statement
-        (4) the desire to not download testdata twice for archive creation
-        testdata archive creation is now inconspicuously posing as a test.
+    Due to intricacies arising from:
+
+    (1) fixtures not working outside of pytest
+    (2) implicit teardown leveraging tempdata removal (while held open by yield)
+    (3) wrappers evaluating the yield statement
+    (4) the desire to not download testdata twice for archive creation
+
+    testdata archive creation is now inconspicuously posing as a test.
     """
 
     testdata_dir = files("bidsschematools.tests.data")

tools/schemacode/bidsschematools/tests/test_render_text.py

@@ -67,12 +67,13 @@ def test_make_glossary(schema_obj, schema_dir):
 def test_make_filename_template(schema_obj, schema_dir):
     """
     Test whether:
-        * the base hierarchy structure of mandatory subject and optional session is
-        returned. This should be robust with respect to schema format.
-        * each directory contains at least one possible pattern.
-        This should be robust with respect to schema format.
-        * all files under the datatype rules subdirectory have corresponding entries.
-        This may need to be updated for schema hierarchy changes.
+
+    * The base hierarchy structure of mandatory subject and optional session is
+      returned. This should be robust with respect to schema format.
+    * Each directory contains at least one possible pattern.
+      This should be robust with respect to schema format.
+    * All files under the datatype rules subdirectory have corresponding entries.
+      This may need to be updated for schema hierarchy changes.
     """
     filename_template = text.make_filename_template("raw", schema_obj, pdf_format=True)
 

tools/schemacode/docs/.gitignore

@@ -0,0 +1 @@
+api/

tools/schemacode/docs/_templates/module.rst

@@ -0,0 +1,68 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+{% block modules %}
+{% if modules %}
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :template: module.rst
+   :recursive:
+{% for item in modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}
+
+.. currentmodule:: {{ fullname }}
+
+{% block attributes %}
+{% if attributes %}
+.. rubric:: {{ _('Module Attributes') }}
+
+{% for item in attributes %}
+.. autoattribute:: {{ item }}
+
+{%- endfor %}
+{% endif %}
+{% endblock %}
+
+{% block classes %}
+{% if classes %}
+.. rubric:: {{ _('Classes') }}
+
+{% for item in classes %}
+
+.. autoclass:: {{ item }}
+   :members:
+   :show-inheritance:
+   :inherited-members:
+   :special-members: __call__, __add__, __mul__
+
+{%- endfor %}
+{% endif %}
+{% endblock %}
+
+{% block functions %}
+{% if functions %}
+.. rubric:: {{ _('Functions') }}
+
+{% for item in functions %}
+.. autofunction:: {{ item }}
+
+{%- endfor %}
+{% endif %}
+{% endblock %}
+
+{% block exceptions %}
+{% if exceptions %}
+.. rubric:: {{ _('Exceptions') }}
+
+{% for item in exceptions %}
+.. autoexception:: {{ item }}
+
+{%- endfor %}
+{% endif %}
+{% endblock %}

tools/schemacode/docs/api.rst

@@ -0,0 +1,9 @@
+Schema Tools API
+================
+
+.. autosummary::
+   :toctree: api
+   :template: module.rst
+   :recursive:
+
+   bidsschematools

tools/schemacode/docs/bidsschematools.rst

@@ -30,13 +30,18 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    "sphinx.ext.intersphinx",
     "sphinx.ext.duration",
     "sphinx.ext.doctest",
     "sphinx.ext.coverage",
     "sphinx.ext.napoleon",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
     "myst_parser",
 ]
 
+autosummary_generate = True
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
@@ -46,6 +51,14 @@
 exclude_patterns = ["_build", "tests"]
 
 
+# Mock internal modules to avoid building docs
+autosummary_mock_imports = [
+    "bidsschematools.conftest",
+]
+
+intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
+
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for

tools/schemacode/docs/conf.py

@@ -5,9 +5,10 @@ Contents
 ========
 
 .. toctree::
-   modules
    :maxdepth: 2
 
+   api
+
 
 Indices and tables
 ==================