docs: Make sure each option is documented

mkdocstrings · Feb 3, 2025 · 95bba88 · 95bba88
1 parent 73292f5
commit 95bba88
Show file tree

Hide file tree

Showing 7 changed files with 93 additions and 31 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
@@ -74,6 +74,7 @@ plugins:
 ////
 ///
 
+[](){#option-parameter_headings}
 ## `parameter_headings`
 
 [:octicons-tag-24: Insiders 1.6.0](../../insiders/changelog.md#1.6.0)
@@ -196,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" }**
@@ -259,6 +261,7 @@ plugins:
 ////
 ///
 
+[](){#option-show_root_toc_entry}
 ## `show_root_toc_entry`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
@@ -316,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" }**
@@ -361,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" }**
@@ -409,6 +414,7 @@ plugins:
 ////
 ///
 
+[](){#option-show_object_full_path}
 ## `show_object_full_path`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
@@ -462,6 +468,7 @@ plugins:
 ////
 ///
 
+[](){#option-show_category_heading}
 ## `show_category_heading`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
@@ -527,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)
@@ -591,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)

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