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 8861f83..8b6218f 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 467779e..9acbcc1 100644 --- a/docs/usage/configuration/headings.md +++ b/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) 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 879db6b..1e82fe6 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 bc498bd..4c22eef 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")