From dcb489d4c2d7ac89af035732585aec0bc7110e67 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Thu, 16 Jan 2025 21:17:18 +0100 Subject: [PATCH] docs: Make sure each option is documented --- docs/usage/configuration/docstrings.md | 23 +++++++- docs/usage/configuration/general.md | 5 ++ docs/usage/configuration/headings.md | 78 +++++++++++++++----------- docs/usage/configuration/members.md | 8 +++ docs/usage/configuration/signatures.md | 10 +++- docs/usage/index.md | 58 ++++++++++--------- scripts/mkdocs_hooks.py | 11 +++- 7 files changed, 129 insertions(+), 64 deletions(-) diff --git a/docs/usage/configuration/docstrings.md b/docs/usage/configuration/docstrings.md index e3461cd..ae925f2 100644 --- 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 } — @@ -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" }** diff --git a/docs/usage/configuration/general.md b/docs/usage/configuration/general.md index b301220..3983a61 100644 --- 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"]

Docstring of your module.

//// /// + +[](){#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 } — @@ -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 index 33062ba..c4f5ced 100644 --- 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" }** + + +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" }** - - -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" }** - - -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: //// /// + +[](){#option-toc_label} +## `toc_label` + +- **:octicons-package-24: Type [`str`][] :material-equal: `""`{ title="default value" }** + + +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" +``` diff --git a/docs/usage/configuration/members.md b/docs/usage/configuration/members.md index 220a26f..363f7e0 100644 --- 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 list[str] | @@ -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 list[str] | @@ -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 list[str] | None :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" }** diff --git a/docs/usage/configuration/signatures.md b/docs/usage/configuration/signatures.md index 345e153..c97cb5a 100644 --- a/docs/usage/configuration/signatures.md +++ b/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" }** diff --git a/docs/usage/index.md b/docs/usage/index.md index 8caafb4..8411093 100644 --- a/docs/usage/index.md +++ b/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. diff --git a/scripts/mkdocs_hooks.py b/scripts/mkdocs_hooks.py index 63e7578..bfa74e5 100644 --- a/scripts/mkdocs_hooks.py +++ b/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")