Streamlined auto api referencing for documentation (#5795)

semohr · web-flow · commit 9584216209c3 · 2025-05-22T11:35:40.000+02:00
## Description

The current developer documentation feels somewhat cluttered due to
inline auto-generated API references for certain classes. To improve
readability and maintainability, this PR introduces a more streamlined
approach that aligns better with best practices observed in other PyData
ecosystem documentation.

Specifically, this PR:
- Adds a dedicated `api/` folder to the documentation structure.
- Moves all auto-generated references (classes, methods, etc.) to this
folder.
- Enables clean, concise linking to API elements from the narrative
documentation—without interrupting human-written content with large
autogenerated blocks.

This separation makes the documentation easier to navigate and maintain,
while still providing full API reference coverage where needed.

- [x] Documentation
- [x] Changelog
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1,2 @@
+_build
+generated/
diff --git a/docs/Makefile b/docs/Makefile
@@ -6,6 +6,7 @@ SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = _build
+SOURCEDIR	  = .
 
 # When both are available, use Sphinx 2.x for autodoc compatibility.
 ifeq ($(shell which sphinx-build2 >/dev/null 2>&1 ; echo $$?),0)
@@ -39,7 +40,7 @@ help:
 	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
 
 clean:
-	-rm -rf $(BUILDDIR)/*
+	-rm -rf $(BUILDDIR)/* $(SOURCEDIR)/api/generated/*
 
 html:
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
diff --git a/docs/_templates/autosummary/base.rst b/docs/_templates/autosummary/base.rst
@@ -0,0 +1,3 @@
+{{ fullname | escape | underline}}
+.. currentmodule:: {{ module }}
+.. auto{{ objtype }}:: {{ objname }}
diff --git a/docs/_templates/autosummary/class.rst b/docs/_templates/autosummary/class.rst
@@ -0,0 +1,28 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+   :members:                                    <-- add at least this line
+   :private-members:
+   :show-inheritance:                           <-- plus I want to show inheritance...
+   :inherited-members:                          <-- ...and inherited members too
+
+   {% block methods %}
+   .. automethod:: __init__
+
+   {% if methods %}
+   .. rubric:: {{ _('Public methods summary') }}
+
+   .. autosummary::
+   {% for item in methods %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% for item in _methods %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   .. rubric:: {{ _('Methods definition') }}
+
diff --git a/docs/_templates/autosummary/module.rst b/docs/_templates/autosummary/module.rst
@@ -0,0 +1,11 @@
+{{ fullname | escape | underline}}
+{% block modules %}
+{% if modules %}
+.. rubric:: Modules
+
+{% for item in modules %}
+{{ item }}
+
+{%- endfor %}
+{% endif %}
+{% endblock %}
diff --git a/docs/api/database.rst b/docs/api/database.rst
@@ -0,0 +1,47 @@
+Database
+--------
+
+.. currentmodule:: beets.library
+
+
+Library
+'''''''
+
+.. autosummary::
+    :toctree: generated/
+
+    Library
+
+
+Models
+''''''
+
+.. autosummary::
+    :toctree: generated/
+
+    LibModel
+    Album
+    Item
+
+
+Transactions
+''''''''''''
+
+.. currentmodule:: beets.dbcore.db
+
+.. autosummary::
+    :toctree: generated/
+
+    Transaction
+
+Queries
+'''''''
+
+.. currentmodule:: beets.dbcore.query
+
+.. autosummary::
+    :toctree: generated/
+
+    Query
+    FieldQuery
+    AndQuery
diff --git a/docs/api/plugins.rst b/docs/api/plugins.rst
@@ -0,0 +1,11 @@
+Plugins
+-------
+
+.. currentmodule:: beets.plugins
+
+
+
+.. autosummary::
+    :toctree: generated/
+
+    BeetsPlugin
diff --git a/docs/changelog.rst b/docs/changelog.rst
@@ -43,16 +43,21 @@ For plugin developers:
 
 Other changes:
 
+* Documentation structure for auto generated API references changed slightly.
+  Autogenerated API references are now located in the `docs/api` subdirectory.
+
 2.3.1 (May 14, 2025)
 --------------------
 
 Bug fixes:
+
 * :doc:`/reference/pathformat`: Fixed a regression where path legalization
   incorrectly removed parts of user-configured path formats that followed a dot
   (**.**).
   :bug:`5771`
 
 For packagers:
+
 * Force ``poetry`` version below 2 to avoid it mangling file modification times
   in ``sdist`` package.
   :bug:`5770`
diff --git a/docs/conf.py b/docs/conf.py
@@ -1,19 +1,35 @@
-AUTHOR = "Adrian Sampson"
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
 
-# General configuration
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-extensions = ["sphinx.ext.autodoc", "sphinx.ext.extlinks"]
-
-exclude_patterns = ["_build"]
-source_suffix = {".rst": "restructuredtext"}
-master_doc = "index"
 
 project = "beets"
+AUTHOR = "Adrian Sampson"
 copyright = "2016, Adrian Sampson"
 
+master_doc = "index"
+language = "en"
 version = "2.3"
 release = "2.3.1"
 
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.extlinks",
+]
+autosummary_generate = True
+exclude_patterns = ["_build"]
+templates_path = ["_templates"]
+source_suffix = {".rst": "restructuredtext", ".md": "markdown"}
+
+
 pygments_style = "sphinx"
 
 # External links to the bug tracker and other sites.
@@ -59,10 +75,24 @@
     ),
 ]
 
-# Options for pydata theme
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+
 html_theme = "pydata_sphinx_theme"
 html_theme_options = {"collapse_navigation": True, "logo": {"text": "beets"}}
 html_title = "beets"
 html_logo = "_static/beets_logo_nobg.png"
 html_static_path = ["_static"]
 html_css_files = ["beets.css"]
+
+
+def skip_member(app, what, name, obj, skip, options):
+    if name.startswith("_"):
+        return True
+    return skip
+
+
+def setup(app):
+    app.connect("autodoc-skip-member", skip_member)
diff --git a/docs/dev/index.rst b/docs/dev/index.rst
@@ -10,8 +10,18 @@ and write metadata tags in media files.
 .. _MediaFile: https://mediafile.readthedocs.io/en/latest/
 
 .. toctree::
+    :maxdepth: 1
 
     plugins
     library
     importer
     cli
+
+
+.. toctree::
+    :maxdepth: 1
+    :caption: API Reference
+
+    ../api/plugins
+    ../api/database
+
diff --git a/docs/dev/library.rst b/docs/dev/library.rst
diff --git a/docs/dev/plugins.rst b/docs/dev/plugins.rst

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+{{ fullname \| escape \| underline}}`
	`2`	`+.. currentmodule:: {{ module }}`
	`3`	`+.. auto{{ objtype }}:: {{ objname }}`