diff --git a/docs/usage/configuration/general.md b/docs/usage/configuration/general.md index 973658c1..68899890 100644 --- a/docs/usage/configuration/general.md +++ b/docs/usage/configuration/general.md @@ -494,3 +494,63 @@ def some_function():

Docstring of the function.

//// /// + +[](){#option-skip_local_inventory} +## `skip_local_inventory` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** + + +Whether to skip registering symbols in the objects inventory. + +With this option enabled, re-rendering docstrings for objects from external inventories is possible with their cross-references pointing to the original external inventory, not local. Similarly, it becomes possible to render the same symbol several times in the same documentation, with only one canonical location being used for cross-references (preventing confusion in mkdocs-autorefs). + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + skip_local_inventory: false +``` + +```md title="or in docs/some_page.md (local configuration)" +::: path.to.module + options: + skip_local_inventory: true +``` + +/// admonition | Preview + type: preview + + +//// tab | Without `skip_local_inventory` + +```md exec="on" +::: bisect.bisect_left + options: + heading_level: 3 + skip_local_inventory: false + show_docstring_description: false +``` + +Notice how [`bisect.bisect_left`][] now points to the section above. + +//// + +//// tab | With `skip_local_inventory` + +```md exec="on" +::: bisect.bisect_right + inventories: + - https://docs.python.org/3/objects.inv + options: + heading_level: 3 + skip_local_inventory: true + show_docstring_description: false +``` + +Notice how [`bisect.bisect_right`][] points to the original Python documentation. + +//// +/// diff --git a/docs/usage/configuration/headings.md b/docs/usage/configuration/headings.md index b4314b77..0c253f1f 100644 --- a/docs/usage/configuration/headings.md +++ b/docs/usage/configuration/headings.md @@ -88,7 +88,7 @@ With this option enabled, each function/method parameter (including parameters of `__init__` methods merged in their parent class with the [`merge_init_into_class`][] option) gets a permalink, an entry in the Table of Contents, -and an entry in the generated objects inventory. +and an entry in the generated objects inventory (unless [`skip_local_inventory`][] is enabled). The permalink and inventory entry allow cross-references from internal and external pages. diff --git a/pyproject.toml b/pyproject.toml index 8adc2a30..9ac5537d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -31,7 +31,7 @@ classifiers = [ "Typing :: Typed", ] dependencies = [ - "mkdocstrings>=0.28.3", + "mkdocstrings>=0.30", "mkdocs-autorefs>=1.4", "griffe>=1.6.2", "typing-extensions>=4.0; python_version < '3.11'", diff --git a/src/mkdocstrings_handlers/python/_internal/config.py b/src/mkdocstrings_handlers/python/_internal/config.py index 6a68e353..4d0d6515 100644 --- a/src/mkdocstrings_handlers/python/_internal/config.py +++ b/src/mkdocstrings_handlers/python/_internal/config.py @@ -865,6 +865,14 @@ class PythonInputOptions: ), ] = False + skip_local_inventory: Annotated[ + bool, + _Field( + group="general", + description="Whether to not give objects local inventory entries.", + ), + ] = False + signature_crossrefs: Annotated[ bool, _Field( diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja index 5832c8bd..bad9ad54 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja @@ -40,6 +40,7 @@ Context: id=html_id, class="doc doc-heading", toc_label=(' '|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else attribute.name), + skip_inventory=config.skip_local_inventory, ) %} {% block heading scoped %} @@ -93,6 +94,7 @@ Context: id=html_id, toc_label=(' '|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else attribute_name), hidden=True, + skip_inventory=config.skip_local_inventory, ) %} {% endfilter %} {% endif %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja index 0b9fcd64..0538aa9a 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja @@ -45,7 +45,7 @@ Context: ) %} {% if attributes %} {% if config.show_category_heading %} - {% filter heading(heading_level, id=html_id ~ "-attributes") %}Attributes{% endfilter %} + {% filter heading(heading_level, id=html_id ~ "-attributes", skip_inventory=config.skip_local_inventory) %}Attributes{% endfilter %} {% endif %} {% with heading_level = heading_level + extra_level %} {% for attribute in attributes|order_members(config.members_order, members_list) %} @@ -65,7 +65,7 @@ Context: ) %} {% if classes %} {% if config.show_category_heading %} - {% filter heading(heading_level, id=html_id ~ "-classes") %}Classes{% endfilter %} + {% filter heading(heading_level, id=html_id ~ "-classes", skip_inventory=config.skip_local_inventory) %}Classes{% endfilter %} {% endif %} {% with heading_level = heading_level + extra_level %} {% for class in classes|order_members(config.members_order, members_list) %} @@ -85,7 +85,7 @@ Context: ) %} {% if functions %} {% if config.show_category_heading %} - {% filter heading(heading_level, id=html_id ~ "-functions") %}Functions{% endfilter %} + {% filter heading(heading_level, id=html_id ~ "-functions", skip_inventory=config.skip_local_inventory) %}Functions{% endfilter %} {% endif %} {% with heading_level = heading_level + extra_level %} {% for function in functions|order_members(config.members_order, members_list) %} @@ -108,7 +108,7 @@ Context: ) %} {% if modules %} {% if config.show_category_heading %} - {% filter heading(heading_level, id=html_id ~ "-modules") %}Modules{% endfilter %} + {% filter heading(heading_level, id=html_id ~ "-modules", skip_inventory=config.skip_local_inventory) %}Modules{% endfilter %} {% endif %} {% with heading_level = heading_level + extra_level %} {% for module in modules|order_members("alphabetical", members_list) %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja index 8a54dd1b..f366f497 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja @@ -39,6 +39,7 @@ Context: id=html_id, class="doc doc-heading", toc_label=(' '|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else class.name), + skip_inventory=config.skip_local_inventory, ) %} {% block heading scoped %} @@ -112,6 +113,7 @@ Context: id=html_id, toc_label=(' '|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else class.name), hidden=True, + skip_inventory=config.skip_local_inventory, ) %} {% endfilter %} {% endif %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html.jinja index 1035ddf7..a3ea5f7f 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html.jinja @@ -43,6 +43,7 @@ Context: id=html_id ~ "(" ~ parameter.name ~ ")", class="doc doc-heading doc-heading-parameter", toc_label=(' '|safe if config.show_symbol_type_toc else '') + parameter.name, + skip_inventory=config.skip_local_inventory, ) %} {{ parameter.name }} {% endfilter %} @@ -92,6 +93,7 @@ Context: id=html_id ~ "(" ~ parameter.name ~ ")", class="doc doc-heading doc-heading-parameter", toc_label=(' '|safe if config.show_symbol_type_toc else '') + parameter.name, + skip_inventory=config.skip_local_inventory, ) %} {{ parameter.name }} {% endfilter %} @@ -139,6 +141,7 @@ Context: id=html_id ~ "(" ~ parameter.name ~ ")", class="doc doc-heading doc-heading-parameter", toc_label=(' '|safe if config.show_symbol_type_toc else '') + parameter.name, + skip_inventory=config.skip_local_inventory, ) %} {{ parameter.name }} {% endfilter %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja index cd97c8db..4c84006e 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja @@ -46,6 +46,7 @@ Context: id=html_id, class="doc doc-heading", toc_label=((' ')|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else function.name), + skip_inventory=config.skip_local_inventory, ) %} {% block heading scoped %} @@ -110,6 +111,7 @@ Context: id=html_id, toc_label=((' ')|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else function.name), hidden=True, + skip_inventory=config.skip_local_inventory, ) %} {% endfilter %} {% endif %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/module.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/module.html.jinja index 283f2654..c5e4a400 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/module.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/module.html.jinja @@ -39,6 +39,7 @@ Context: id=html_id, class="doc doc-heading", toc_label=(' '|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else module.name), + skip_inventory=config.skip_local_inventory, ) %} {% block heading scoped %} @@ -76,6 +77,7 @@ Context: id=html_id, toc_label=(' '|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else module.name), hidden=True, + skip_inventory=config.skip_local_inventory, ) %} {% endfilter %} {% endif %}