Capitalization and some more minor adjustments. Updated docstrfmt.

docs/dev/index.rst

@@ -13,7 +13,7 @@ configuration files, respectively.
 .. _mediafile: https://mediafile.readthedocs.io/en/latest/
 
 .. toctree::
-    :maxdepth: 1
+    :maxdepth: 2
     :titlesonly:
 
     plugins/index

docs/dev/plugins/autotagger.rst

@@ -47,15 +47,18 @@ Here`s a minimal example:
 
         def album_for_id(self, album_id: str): ...
 
-How Metadata Lookup Works
+Each metadata source plugin automatically gets a unique identifier. You can
--------------------------
+access this identifier using the :py:meth:`~MetadataSourcePlugin.data_source`
+class property to tell plugins apart.
+
+Metadata lookup
+---------------
 
 When beets runs the autotagger, it queries **all enabled metadata source
 plugins** for potential matches:
 
 - For **albums**, it calls :py:meth:`~MetadataSourcePlugin.candidates`.
-- For **individual items**, it calls
+- For **singletons**, it calls :py:meth:`~MetadataSourcePlugin.item_candidates`.
-  :py:meth:`~MetadataSourcePlugin.item_candidates`.
 
 The results are combined and scored. By default, candidate ranking is handled
 automatically by the beets core, but you can customize weighting by overriding:
@@ -66,20 +69,19 @@ automatically by the beets core, but you can customize weighting by overriding:
 This is optional, if not overridden, both methods return a constant distance of
 `0.5`.
 
-Implementing ID-based Lookups
+ID-based lookups
------------------------------
+----------------
 
 Your plugin must also define:
 
 - :py:meth:`~MetadataSourcePlugin.album_for_id` — fetch album metadata by ID.
 - :py:meth:`~MetadataSourcePlugin.track_for_id` — fetch track metadata by ID.
 
-These methods should return `None` if your source doesn`t support ID lookups.
 IDs are expected to be strings. If your source uses specific formats, consider
 contributing an extractor regex to the core module:
 :py:mod:`beets.util.id_extractors`.
 
-Best Practices
+Best practices
 --------------
 
 Beets already ships with several metadata source plugins. Studying these
@@ -90,7 +92,7 @@ starting points include:
 - `deezer`
 - `discogs`
 
-Migration Guidance
+Migration guidance
 ------------------
 
 Older metadata plugins that extend :py:class:`beets.plugins.BeetsPlugin` should
@@ -101,3 +103,5 @@ in **beets v3.0.0**.
 
     - :py:mod:`beets.autotag`
     - :py:mod:`beets.metadata_plugins`
+    - :ref:`autotagger_extensions`
+    - :ref:`using-the-auto-tagger`

docs/dev/plugins/index.rst

@@ -94,7 +94,7 @@ For more information on writing plugins, feel free to check out the following
 resources:
 
 .. toctree::
-    :maxdepth: 2
+    :maxdepth: 3
     :includehidden:
 
     commands

docs/guides/tagger.rst

@@ -1,3 +1,5 @@
+.. _using-the-auto-tagger:
+
 Using the Auto-Tagger
 =====================
 

poetry.lock

@@ -696,13 +696,13 @@ files = [
 
 [[package]]
 name = "docstrfmt"
-version = "1.11.0"
+version = "1.11.1"
 description = "docstrfmt: A formatter for Sphinx flavored reStructuredText."
 optional = false
 python-versions = ">=3.9"
 files = [
-    {file = "docstrfmt-1.11.0-py3-none-any.whl", hash = "sha256:3d56bdd6e083091a8c5d7db098684f281de84667f4b7d4cc806092a63efc4844"},
+    {file = "docstrfmt-1.11.1-py3-none-any.whl", hash = "sha256:6782d8663321c3a7c40be08a36fbcb1ea9e46d1efba85411ba807d97f384871a"},
-    {file = "docstrfmt-1.11.0.tar.gz", hash = "sha256:37500c8086770294f265187c375c5c35a91a334d2c0b4f764aeace069d4ed501"},
+    {file = "docstrfmt-1.11.1.tar.gz", hash = "sha256:d41e19d6c5d524cc7f8ff6cbfecb8762d77e696b9fe4f5057269051fb966fc80"},
 ]
 
 [package.dependencies]
@@ -711,6 +711,7 @@ click = ">=8"
 docutils = ">=0.20"
 libcst = ">=1"
 platformdirs = ">=4"
+roman = "*"
 sphinx = ">=7"
 tabulate = ">=0.9"
 toml = {version = ">=0.10", markers = "python_version < \"3.11\""}
@@ -2921,6 +2922,17 @@ urllib3 = ">=1.25.10,<3.0"
 [package.extras]
 tests = ["coverage (>=6.0.0)", "flake8", "mypy", "pytest (>=7.0.0)", "pytest-asyncio", "pytest-cov", "pytest-httpserver", "tomli", "tomli-w", "types-PyYAML", "types-requests"]
 
+[[package]]
+name = "roman"
+version = "5.1"
+description = "Integer to Roman numerals converter"
+optional = false
+python-versions = ">=3.9"
+files = [
+    {file = "roman-5.1-py3-none-any.whl", hash = "sha256:bf595d8a9bc4a8e8b1dfa23e1d4def0251b03b494786df6b8c3d3f1635ce285a"},
+    {file = "roman-5.1.tar.gz", hash = "sha256:3a86572e9bc9183e771769601189e5fa32f1620ffeceebb9eca836affb409986"},
+]
+
 [[package]]
 name = "ruff"
 version = "0.12.3"
@@ -3617,4 +3629,4 @@ web = ["flask", "flask-cors"]
 [metadata]
 lock-version = "2.0"
 python-versions = ">=3.9,<4"
-content-hash = "b68f663437ec41a92319456277243438a5c5f5c5f3dca113df1d7cac1b78703a"
+content-hash = "faea27878ce1ca3f1335fd83e027b289351c51c73550bda72bf501a9c82166f7"

pyproject.toml

@@ -100,7 +100,7 @@ requests_oauthlib = "*"
 responses = ">=0.3.0"
 
 [tool.poetry.group.lint.dependencies]
-docstrfmt = ">=1.11.0"
+docstrfmt = ">=1.11.1"
 ruff = ">=0.6.4"
 sphinx-lint = ">=1.0.0"