docs: Make sure each option is documented

mkdocstrings · Jan 29, 2025 · dcb489d · dcb489d
1 parent aace13e
commit dcb489d
Show file tree

Hide file tree

Showing 7 changed files with 129 additions and 64 deletions.
diff --git a/docs/usage/configuration/docstrings.md b/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 } &mdash;
@@ -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 } &mdash;
@@ -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" }**

diff --git a/docs/usage/configuration/general.md b/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" }**

diff --git a/docs/usage/configuration/headings.md b/docs/usage/configuration/headings.md
@@ -1,5 +1,22 @@
 # Headings options
 
+[](){#option-heading}
+## `heading`
+
+- **:octicons-package-24: Type [`str`][] :material-equal: `""`{ title="default value" }**
+<!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
+
+A custom string to use as the heading of the root object (i.e. the object specified directly after the identifier `:::`). This will override the default heading generated by the plugin. See also the [`toc_label` option.][]
+
+WARNING: **Not advised to be used as a global configuration option.** This option is not advised to be used as a global configuration option, as it will override the default heading for all objects. It is recommended to use it only in specific cases where you want to override the heading for a specific object.
+
+```md title="in docs/some_page.md (local configuration)"
+::: path.to.module
+    options:
+      heading: "My fancy module"
+```
+
+[](){#option-heading_level}
 ## `heading_level`
 
 - **:octicons-package-24: Type [`int`][] :material-equal: `2`{ title="default value" }**
@@ -57,39 +74,7 @@ plugins:
 ////
 ///
 
-## `heading`
-
-- **:octicons-package-24: Type [`str`][] :material-equal: `""`{ title="default value" }**
-<!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
-
-A custom string to use as the heading of the root object (i.e. the object specified directly after the identifier `:::`). This will override the default heading generated by the plugin.
-
-WARNING: **Not advised to be used as a global configuration option.** This option is not advised to be used as a global configuration option, as it will override the default heading for all objects. It is recommended to use it only in specific cases where you want to override the heading for a specific object.
-
-```md title="in docs/some_page.md (local configuration)"
-::: path.to.module
-    options:
-      heading: "My fancy module"
-```
-
-## `toc_label`
-
-- **:octicons-package-24: Type [`str`][] :material-equal: `""`{ title="default value" }**
-<!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
-
-A custom string to use as the label in the Table of Contents for the root object (i.e. the one specified directly after the identifier `:::`). This will override the default label generated by the plugin.
-
-WARNING: **Not advised to be used as a global configuration option.** This option is not advised to be used as a global configuration option, as it will override the default label for all objects. It is recommended to use it only in specific cases where you want to override the label for a specific object.
-
-NOTE: **Use with/without `heading`.** If you use this option without specifying a custom `heading`, the default heading will be used in the page, but the label in the Table of Contents will be the one you specified. By providing both an option for `heading` and `toc_label`, we leave the customization entirely up to you.
-
-```md title="in docs/some_page.md (local configuration)"
-::: path.to.module
-    options:
-      heading: "My fancy module"
-      toc_label: "My fancy module"
-```
-
+[](){#option-parameter_headings}
 ## `parameter_headings`
 
 [:octicons-tag-24: Insiders 1.6.0](../../insiders/changelog.md#1.6.0)
@@ -212,6 +197,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" }**
@@ -275,6 +261,7 @@ plugins:
 ////
 ///
 
+[](){#option-show_root_toc_entry}
 ## `show_root_toc_entry`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
@@ -332,6 +319,7 @@ More text.
 ////
 ///
 
+[](){#option-show_root_full_path}
 ## `show_root_full_path`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
@@ -377,6 +365,7 @@ plugins:
 ////
 ///
 
+[](){#option-show_root_members_full_path}
 ## `show_root_members_full_path`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
@@ -425,6 +414,7 @@ plugins:
 ////
 ///
 
+[](){#option-show_object_full_path}
 ## `show_object_full_path`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
@@ -478,6 +468,7 @@ plugins:
 ////
 ///
 
+[](){#option-show_category_heading}
 ## `show_category_heading`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
@@ -543,6 +534,7 @@ plugins:
 ////
 ///
 
+[](){#option-show_symbol_type_heading}
 ## `show_symbol_type_heading`
 
 [:octicons-tag-24: Insiders 1.1.0](../../insiders/changelog.md#1.1.0)
@@ -607,6 +599,7 @@ plugins:
 ////
 ///
 
+[](){#option-show_symbol_type_toc}
 ## `show_symbol_type_toc`
 
 [:octicons-tag-24: Insiders 1.1.0](../../insiders/changelog.md#1.1.0)
@@ -670,3 +663,22 @@ plugins:
 </ul>
 ////
 ///
+
+[](){#option-toc_label}
+## `toc_label`
+
+- **:octicons-package-24: Type [`str`][] :material-equal: `""`{ title="default value" }**
+<!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
+
+A custom string to use as the label in the Table of Contents for the root object (i.e. the one specified directly after the identifier `:::`). This will override the default label generated by the plugin. See also the [`heading` option.][]
+
+WARNING: **Not advised to be used as a global configuration option.** This option is not advised to be used as a global configuration option, as it will override the default label for all objects. It is recommended to use it only in specific cases where you want to override the label for a specific object.
+
+NOTE: **Use with/without `heading`.** If you use this option without specifying a custom `heading`, the default heading will be used in the page, but the label in the Table of Contents will be the one you specified. By providing both an option for `heading` and `toc_label`, we leave the customization entirely up to you.
+
+```md title="in docs/some_page.md (local configuration)"
+::: path.to.module
+    options:
+      heading: "My fancy module"
+      toc_label: "My fancy module"
+```