docs: Make sure each option is documented

docs/usage/configuration/docstrings.md

@@ -1,5 +1,6 @@
 # Docstrings options
 
+[](){#option-docstring_style}
 ## `docstring_style`
 
 - **:octicons-package-24: Type [`str`][] :material-equal: `"google"`{ title="default value" }**
@@ -84,6 +85,7 @@ def greet(name: str) -> str:
 ////
 ///
 
+[](){#option-docstring_options}
 ## `docstring_options`
 
 - **:octicons-package-24: Type [`dict`][] :material-equal: `{}`{ title="default value" }**
@@ -158,6 +160,7 @@ ok
 ////
 ///
 
+[](){#option-docstring_section_style}
 ## `docstring_section_style`
 
 - **:octicons-package-24: Type [`str`][] :material-equal: `"table"`{ title="default value" }**
@@ -249,6 +252,7 @@ by reserving more horizontal space on the second column.
 ////
 ///
 
+[](){#option-merge_init_into_class}
 ## `merge_init_into_class`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
@@ -320,6 +324,7 @@ class Thing:
 ////
 ///
 
+[](){#option-relative_crossrefs}
 ## `relative_crossrefs`
 
 [:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } —
@@ -432,6 +437,7 @@ class Class:
 
 INFO: **There is an alternative, third-party Python handler that handles relative references: [mkdocstrings-python-xref](https://github.com/analog-garage/mkdocstrings-python-xref).**
 
+[](){#option-scoped_crossrefs}
 ## `scoped_crossrefs`
 
 [:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } —
@@ -452,7 +458,7 @@ The following order is applied when resolving a name in a given scope:
 
 In practice, it means that the name is first looked up in members, then it is compared against the parent name (only if it's a class), then it is looked up in siblings. It continues climbing up the object tree until there's no parent, in which case it raises a name resolution error.
 
-Cross-referencing an imported object will directly link to this object if the objects inventory of the project it comes from was [loaded][import]. You won't be able to cross-reference it within your own documentation with scoped references, if you happen to be rendering this external object too. In that case, you can use an absolute reference or a [relative][relative_crossrefs] one instead.
+Cross-referencing an imported object will directly link to this object if the objects inventory of the project it comes from was [loaded][inventories]. You won't be able to cross-reference it within your own documentation with scoped references, if you happen to be rendering this external object too. In that case, you can use an absolute reference or a [relative][relative_crossrefs] one instead.
 
 Another limitation is that you won't be able to reference an external package if its name can be resolved in the current object's scope.
 
@@ -541,6 +547,7 @@ class Class:
 
 ///
 
+[](){#option-show_if_no_docstring}
 ## `show_if_no_docstring`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
@@ -610,6 +617,7 @@ class ClassWithoutDocstring:
 ////
 ///
 
+[](){#option-show_docstring_attributes}
 ## `show_docstring_attributes`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
@@ -662,6 +670,7 @@ class Class:
 ////
 ///
 
+[](){#option-show_docstring_functions}
 ## `show_docstring_functions`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
@@ -736,7 +745,7 @@ class Class:
 ////
 ///
 
-
+[](){#option-show_docstring_classes}
 ## `show_docstring_classes`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
@@ -795,6 +804,7 @@ class Class:
 ////
 ///
 
+[](){#option-show_docstring_modules}
 ## `show_docstring_modules`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
@@ -851,6 +861,7 @@ Modules:
 ////
 ///
 
+[](){#option-show_docstring_description}
 ## `show_docstring_description`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
@@ -914,6 +925,7 @@ class Class:
 ////
 ///
 
+[](){#option-show_docstring_examples}
 ## `show_docstring_examples`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
@@ -967,6 +979,7 @@ hello
 ////
 ///
 
+[](){#option-show_docstring_other_parameters}
 ## `show_docstring_other_parameters`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
@@ -1017,6 +1030,7 @@ def do_something(**kwargs):
 ////
 ///
 
+[](){#option-show_docstring_parameters}
 ## `show_docstring_parameters`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
@@ -1067,6 +1081,7 @@ def do_something(whatever: int = 0):
 ////
 ///
 
+[](){#option-show_docstring_raises}
 ## `show_docstring_raises`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
@@ -1118,6 +1133,7 @@ def raise_runtime_error():
 ////
 ///
 
+[](){#option-show_docstring_receives}
 ## `show_docstring_receives`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
@@ -1177,6 +1193,7 @@ def iter_skip(
 ////
 ///
 
+[](){#option-show_docstring_returns}
 ## `show_docstring_returns`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
@@ -1228,6 +1245,7 @@ def rand() -> int:
 ////
 ///
 
+[](){#option-show_docstring_warns}
 ## `show_docstring_warns`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
@@ -1279,6 +1297,7 @@ def warn():
 ////
 ///
 
+[](){#option-show_docstring_yields}
 ## `show_docstring_yields`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**

docs/usage/configuration/general.md

@@ -1,5 +1,6 @@
 # General options
 
+[](){#option-allow_inspection}
 ## `allow_inspection`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
@@ -281,6 +282,8 @@ __all__ = ["their_object"]
 <p>Docstring of your module.</p>
 ////
 ///
+
+[](){#option-show_bases}
 ## `show_bases`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
@@ -318,6 +321,7 @@ plugins:
 ////
 ///
 
+[](){#option-show_inheritance_diagram}
 ## `show_inheritance_diagram`
 
 [:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } &mdash;
@@ -403,6 +407,7 @@ Mixin2A --> Mixin2B
 because these classes do not exist in our documentation.*
 ///
 
+[](){#option-show_source}
 ## `show_source`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**

docs/usage/configuration/headings.md

@@ -1,5 +1,6 @@
 # Headings options
 
+[](){#option-heading_level}
 ## `heading_level`
 
 - **:octicons-package-24: Type [`int`][] :material-equal: `2`{ title="default value" }**
@@ -57,6 +58,7 @@ plugins:
 ////
 ///
 
+[](){#option-parameter_headings}
 ## `parameter_headings`
 
 [:octicons-tag-24: Insiders 1.6.0](../../insiders/changelog.md#1.6.0)
@@ -179,6 +181,7 @@ To customize symbols, see [Customizing symbol types](../customization.md/#symbol
 
 ///
 
+[](){#option-show_root_heading}
 ## `show_root_heading`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
@@ -242,6 +245,7 @@ plugins:
 ////
 ///
 
+[](){#option-show_root_toc_entry}
 ## `show_root_toc_entry`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
@@ -299,6 +303,7 @@ More text.
 ////
 ///
 
+[](){#option-show_root_full_path}
 ## `show_root_full_path`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
@@ -344,6 +349,7 @@ plugins:
 ////
 ///
 
+[](){#option-show_root_members_full_path}
 ## `show_root_members_full_path`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
@@ -392,6 +398,7 @@ plugins:
 ////
 ///
 
+[](){#option-show_object_full_path}
 ## `show_object_full_path`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
@@ -445,6 +452,7 @@ plugins:
 ////
 ///
 
+[](){#option-show_category_heading}
 ## `show_category_heading`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
@@ -510,6 +518,7 @@ plugins:
 ////
 ///
 
+[](){#option-show_symbol_type_heading}
 ## `show_symbol_type_heading`
 
 [:octicons-tag-24: Insiders 1.1.0](../../insiders/changelog.md#1.1.0)
@@ -574,6 +583,7 @@ plugins:
 ////
 ///
 
+[](){#option-show_symbol_type_toc}
 ## `show_symbol_type_toc`
 
 [:octicons-tag-24: Insiders 1.1.0](../../insiders/changelog.md#1.1.0)

docs/usage/configuration/members.md

@@ -1,5 +1,6 @@
 # Members options
 
+[](){#option-members}
 ## `members`
 
 - **:octicons-package-24: Type <code><autoref identifier="list" optional>list</autoref>[<autoref identifier="str" optional>str</autoref>] |
@@ -95,6 +96,7 @@ this_attribute = 0
 
 INFO: **The default behavior (with unspecified `members` or `members: null`) is to use [`filters`][].**
 
+[](){#option-inherited_members}
 ## `inherited_members`
 
 - **:octicons-package-24: Type <code><autoref identifier="list" optional>list</autoref>[<autoref identifier="str" optional>str</autoref>] |
@@ -259,6 +261,7 @@ class Main(Base):
 
 ///
 
+[](){#option-members_order}
 ## `members_order`
 
 - **:octicons-package-24: Type [`str`][] :material-equal: `"alphabetical"`{ title="default value" }**
@@ -329,6 +332,7 @@ def function_c():
 ////
 ///
 
+[](){#option-filters}
 ## `filters`
 
 - **:octicons-package-24: Type <code><autoref identifier="list" optional>list</autoref>[<autoref identifier="str" optional>str</autoref>] | None</code>  :material-equal: `["!^_[^_]"]`{ title="default value" }**
@@ -427,6 +431,7 @@ Here are some common filters that you might to want to use.
 - `["!^_[^_]"]`: exclude all private/protected objects, keep special ones (default filters)
 ///
 
+[](){#option-group_by_category}
 ## `group_by_category`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
@@ -496,6 +501,7 @@ def function_d():
 ////
 ///
 
+[](){#option-show_submodules}
 ## `show_submodules`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
@@ -550,6 +556,7 @@ package
 ////
 ///
 
+[](){#option-summary}
 ## `summary`
 
 [:octicons-tag-24: Insiders 1.2.0](../../insiders/changelog.md#1.2.0)
@@ -643,6 +650,7 @@ plugins:
 ////
 ///
 
+[](){#option-show_labels}
 ## `show_labels`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**

docs/usage/configuration/signatures.md

@@ -1,5 +1,6 @@
 # Signatures options
 
+[](){#option-annotations_path}
 ## `annotations_path`
 
 - **:octicons-package-24: Type [`str`][] :material-equal: `"brief"`{ title="default value" }**
@@ -146,6 +147,7 @@ def convert(text: str, md: Markdown) -> Markup:
 ////
 ///
 
+[](){#option-line_length}
 ## `line_length`
 
 - **:octicons-package-24: Type [`int`][] :material-equal: `60`{ title="default value" }**
@@ -198,6 +200,7 @@ plugins:
 ////
 ///
 
+[](){#option-modernize_annotations}
 ## `modernize_annotations`
 
 [:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } —
@@ -283,8 +286,7 @@ plugins:
 
 ///
 
-
-
+[](){#option-show_signature}
 ## `show_signature`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
@@ -323,6 +325,7 @@ plugins:
 ////
 ///
 
+[](){#option-show_signature_annotations}
 ## `show_signature_annotations`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
@@ -377,6 +380,7 @@ function(param1, param2=None)
 ////
 ///
 
+[](){#option-separate_signature}
 ## `separate_signature`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
@@ -429,6 +433,7 @@ function(param1, param2=None)
 ////
 ///
 
+[](){#option-signature_crossrefs}
 ## `signature_crossrefs`
 
 [:octicons-tag-24: Insiders 1.0.0](../../insiders/changelog.md#1.0.0)
@@ -476,6 +481,7 @@ plugins:
 ////
 ///
 
+[](){#option-unwrap_annotated}
 ## `unwrap_annotated`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**

docs/usage/index.md

@@ -75,10 +75,11 @@ plugins:
 
 Some options are **global only**, and go directly under the handler's name.
 
-#### `import`
+[](){#setting-inventories}
+#### `inventories`
 
-This option is used to import Sphinx-compatible objects inventories from other
-documentation sites. For example, you can import the standard library
+This option is used to load Sphinx-compatible objects inventories from other
+documentation sites. For example, you can load the standard library
 objects inventory like this:
 
 ```yaml title="mkdocs.yml"
@@ -90,9 +91,9 @@ plugins:
         - https://docs.python-requests.org/en/master/objects.inv
 ```
 
-When importing an inventory, you enable automatic cross-references
+When loading an inventory, you enable automatic cross-references
 to other documentation sites like the standard library docs
-or any third-party package docs. Typically, you want to import
+or any third-party package docs. Typically, you want to load
 the inventories of your project's dependencies, at least those
 that are used in the public API. 
 
@@ -101,8 +102,8 @@ for more details.
 
   [inventories]: https://mkdocstrings.github.io/usage/#cross-references-to-other-projects-inventories
 
-Additionally, the Python handler accepts a `domains` option in the import items,
-which allows to select the inventory domains to select.
+Additionally, the Python handler accepts a `domains` option in the inventory options,
+which allows to select the inventory domains to load.
 By default the Python handler only selects the `py` domain (for Python objects).
 You might find useful to also enable the [`std` domain][std domain]:
 
@@ -113,29 +114,12 @@ plugins:
 - mkdocstrings:
     handlers:
       python:
-        import:
+        inventories:
         - url: https://docs.python-requests.org/en/master/objects.inv
           domains: [std, py]
 ```
 
-NOTE: The `import` option is common to *all* handlers, however
-they might implement it differently, or not even implement it.
-
-#### `paths`
-
-This option is used to provide filesystem paths in which to search for Python modules.
-Non-absolute paths are computed as relative to MkDocs configuration file. Example:
-
-```yaml title="mkdocs.yml"
-plugins:
-- mkdocstrings:
-    handlers:
-      python:
-        paths: [src]  # search packages in the src folder
-```
-
-More details at [Finding modules](#finding-modules).
-
+[](){#setting-load_external_modules}
 #### `load_external_modules`
 
 This option allows resolving aliases (imports) to any external module.
@@ -165,6 +149,28 @@ plugins:
 
   [__all__]: https://docs.python.org/3/tutorial/modules.html#importing-from-a-package
 
+[](){#setting-locale}
+#### `locale`
+
+The locale to use when translating template strings. The translation system is not fully ready yet, so we don't recommend setting the option for now.
+
+[](){#setting-paths}
+#### `paths`
+
+This option is used to provide filesystem paths in which to search for Python modules.
+Non-absolute paths are computed as relative to MkDocs configuration file. Example:
+
+```yaml title="mkdocs.yml"
+plugins:
+- mkdocstrings:
+    handlers:
+      python:
+        paths: [src]  # search packages in the src folder
+```
+
+More details at [Finding modules](#finding-modules).
+
+[](){#setting-options}
 ### Global/local options
 
 The other options can be used both globally *and* locally, under the `options` key.

scripts/mkdocs_hooks.py

@@ -1,13 +1,14 @@
 """Generate a JSON schema of the Python handler configuration."""
 
 import json
+from dataclasses import fields
 from os.path import join
 from typing import Any
 
 from mkdocs.config.defaults import MkDocsConfig
 from mkdocs.plugins import get_plugin_logger
 
-from mkdocstrings_handlers.python.config import PythonInputConfig
+from mkdocstrings_handlers.python.config import PythonInputConfig, PythonInputOptions
 
 # TODO: Update when Pydantic supports Python 3.14 (sources and duties as well).
 try:
@@ -30,3 +31,11 @@ def on_post_build(config: MkDocsConfig, **kwargs: Any) -> None:  # noqa: ARG001
     with open(join(config.site_dir, "schema.json"), "w") as file:
         json.dump(schema, file, indent=2)
         logger.debug("Generated JSON schema")
+
+    autorefs = config["plugins"]["autorefs"]
+    for field in fields(PythonInputConfig):
+        if f"setting-{field.name}" not in autorefs._primary_url_map:
+            logger.warning(f"Handler setting `{field.name}` is not documented")
+    for field in fields(PythonInputOptions):
+        if f"option-{field.name}" not in autorefs._primary_url_map:
+            logger.warning(f"Configuration option `{field.name}` is not documented")