From d57c79c5fcfd6ff519b913c57563689d4facf385 Mon Sep 17 00:00:00 2001 From: bswck Date: Sun, 13 Jul 2025 19:59:54 +0200 Subject: [PATCH 1/9] Use upstream PR branch to install mkdocstrings --- pyproject.toml | 3 +++ 1 file changed, 3 insertions(+) diff --git a/pyproject.toml b/pyproject.toml index d93cb20..54dc64a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -122,3 +122,6 @@ format-command = "ruff format --config config/ruff.toml --stdin-filename {filena [tool.uv] default-groups = ["maintain", "ci", "docs"] + +[tool.uv.sources] +mkdocstrings = { git = "https://github.com/mkdocstrings/mkdocstrings", rev = "bartosz/flag-skip-inventory" } From 63df2c81f643398e35932e211aabf6652090bb02 Mon Sep 17 00:00:00 2001 From: bswck Date: Sun, 13 Jul 2025 20:00:10 +0200 Subject: [PATCH 2/9] Implement `skip_local_inventory` option --- src/mkdocstrings_handlers/python/_internal/config.py | 8 ++++++++ .../python/templates/material/_base/attribute.html.jinja | 2 ++ .../python/templates/material/_base/children.html.jinja | 8 ++++---- .../python/templates/material/_base/class.html.jinja | 2 ++ .../material/_base/docstring/parameters.html.jinja | 3 +++ .../python/templates/material/_base/function.html.jinja | 2 ++ .../python/templates/material/_base/module.html.jinja | 2 ++ 7 files changed, 23 insertions(+), 4 deletions(-) diff --git a/src/mkdocstrings_handlers/python/_internal/config.py b/src/mkdocstrings_handlers/python/_internal/config.py index 5565e9b..562136f 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="headings", + description="Whether to not give objects local inventory entries and permalinks.", + ), + ] = 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 5832c8b..bad9ad5 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 0b9fcd6..0538aa9 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 8a54dd1..f366f49 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 1035ddf..a3ea5f7 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 cd97c8d..4c84006 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 283f265..c5e4a40 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 %} From b06b0dc936358b4b5e7f0a56de1b535857046268 Mon Sep 17 00:00:00 2001 From: bswck Date: Sun, 13 Jul 2025 20:00:21 +0200 Subject: [PATCH 3/9] Add `skip_local_inventory` docs --- docs/usage/configuration/headings.md | 64 +++++++++++++++++++++++++++- 1 file changed, 63 insertions(+), 1 deletion(-) diff --git a/docs/usage/configuration/headings.md b/docs/usage/configuration/headings.md index b4314b7..6d1b7d2 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. @@ -664,6 +664,68 @@ plugins: //// /// + +[](){#option-skip_local_inventory} +## `skip_local_inventory` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** + + +Whether to not give objects local inventory entries and permalinks. + +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. + +```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 | With `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 | Without `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. + +//// + +/// + [](){#option-toc_label} ## `toc_label` From 5a643f94717dd3ee121833476c6bcb59719a02aa Mon Sep 17 00:00:00 2001 From: bswck Date: Sun, 13 Jul 2025 20:17:53 +0200 Subject: [PATCH 4/9] Fix docs --- docs/usage/configuration/headings.md | 2 +- src/mkdocstrings_handlers/python/_internal/config.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/usage/configuration/headings.md b/docs/usage/configuration/headings.md index 6d1b7d2..2b9b33a 100644 --- a/docs/usage/configuration/headings.md +++ b/docs/usage/configuration/headings.md @@ -671,7 +671,7 @@ plugins: - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** -Whether to not give objects local inventory entries and permalinks. +Whether to not give objects local inventory entries. 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. diff --git a/src/mkdocstrings_handlers/python/_internal/config.py b/src/mkdocstrings_handlers/python/_internal/config.py index 562136f..fda2eb3 100644 --- a/src/mkdocstrings_handlers/python/_internal/config.py +++ b/src/mkdocstrings_handlers/python/_internal/config.py @@ -869,7 +869,7 @@ class PythonInputOptions: bool, _Field( group="headings", - description="Whether to not give objects local inventory entries and permalinks.", + description="Whether to not give objects local inventory entries.", ), ] = False From 8c5520549b93ff560abf7fcad5fbdf5b83c03aa5 Mon Sep 17 00:00:00 2001 From: bswck Date: Mon, 14 Jul 2025 12:40:45 +0200 Subject: [PATCH 5/9] Fix tab names --- docs/usage/configuration/headings.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/usage/configuration/headings.md b/docs/usage/configuration/headings.md index 2b9b33a..4ac19e3 100644 --- a/docs/usage/configuration/headings.md +++ b/docs/usage/configuration/headings.md @@ -694,7 +694,7 @@ plugins: type: preview -//// tab | With `skip_local_inventory` +//// tab | Without `skip_local_inventory` ```md exec="on" ::: bisect.bisect_left @@ -708,7 +708,7 @@ Notice how [`bisect.bisect_left`][] now points to the section above. //// -//// tab | Without `skip_local_inventory` +//// tab | With `skip_local_inventory` ```md exec="on" ::: bisect.bisect_right From 3c4e610ee04e2c81fc0d46a84e6508f9e18522c6 Mon Sep 17 00:00:00 2001 From: bswck Date: Mon, 14 Jul 2025 12:46:25 +0200 Subject: [PATCH 6/9] Move `skip_local_inventory` to general options --- docs/usage/configuration/general.md | 60 ++++++++++++++++++ docs/usage/configuration/headings.md | 62 ------------------- .../python/_internal/config.py | 2 +- 3 files changed, 61 insertions(+), 63 deletions(-) diff --git a/docs/usage/configuration/general.md b/docs/usage/configuration/general.md index 973658c..cc2d921 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 not give objects local inventory entries. + +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. + +```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 4ac19e3..0c253f1 100644 --- a/docs/usage/configuration/headings.md +++ b/docs/usage/configuration/headings.md @@ -664,68 +664,6 @@ plugins: //// /// - -[](){#option-skip_local_inventory} -## `skip_local_inventory` - -- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** - - -Whether to not give objects local inventory entries. - -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. - -```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. - -//// - -/// - [](){#option-toc_label} ## `toc_label` diff --git a/src/mkdocstrings_handlers/python/_internal/config.py b/src/mkdocstrings_handlers/python/_internal/config.py index fda2eb3..0f830b0 100644 --- a/src/mkdocstrings_handlers/python/_internal/config.py +++ b/src/mkdocstrings_handlers/python/_internal/config.py @@ -868,7 +868,7 @@ class PythonInputOptions: skip_local_inventory: Annotated[ bool, _Field( - group="headings", + group="general", description="Whether to not give objects local inventory entries.", ), ] = False From ae0406b95dc422739ed9d4b054d8319c3fb2306d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Wed, 23 Jul 2025 19:41:22 +0200 Subject: [PATCH 7/9] Revert "Use upstream PR branch to install mkdocstrings" This reverts commit d57c79c5fcfd6ff519b913c57563689d4facf385. --- pyproject.toml | 3 --- 1 file changed, 3 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 54dc64a..d93cb20 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -122,6 +122,3 @@ format-command = "ruff format --config config/ruff.toml --stdin-filename {filena [tool.uv] default-groups = ["maintain", "ci", "docs"] - -[tool.uv.sources] -mkdocstrings = { git = "https://github.com/mkdocstrings/mkdocstrings", rev = "bartosz/flag-skip-inventory" } From 57cc437924c309bd4c2efb3b52fc88e0cc551ad8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Wed, 23 Jul 2025 19:54:55 +0200 Subject: [PATCH 8/9] depend on mkdocstrings 0.30 --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index d93cb20..8bf0f53 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'", From 7145c1528e4de7e974a6f0d0f8a205d1197695f0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Wed, 23 Jul 2025 20:04:43 +0200 Subject: [PATCH 9/9] docs --- docs/usage/configuration/general.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/usage/configuration/general.md b/docs/usage/configuration/general.md index cc2d921..6889989 100644 --- a/docs/usage/configuration/general.md +++ b/docs/usage/configuration/general.md @@ -501,9 +501,9 @@ def some_function(): - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }** -Whether to not give objects local inventory entries. +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. +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: