feat: Add skip_local_inventory option to not register objects in the local inventory

docs/usage/configuration/general.md

@@ -494,3 +494,63 @@ def some_function():
 <p>Docstring of the function.</p>
 ////
 ///
+
+[](){#option-skip_local_inventory}
+## `skip_local_inventory`
+
+- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
+<!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
+
+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.
+
+////
+///

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.
 

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" }

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(

src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja

@@ -40,6 +40,7 @@ Context:
           id=html_id,
           class="doc doc-heading",
           toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-attribute"></code>&nbsp;'|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=('<code class="doc-symbol doc-symbol-toc doc-symbol-attribute"></code>&nbsp;'|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 %}

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) %}

src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja

@@ -39,6 +39,7 @@ Context:
           id=html_id,
           class="doc doc-heading",
           toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-class"></code>&nbsp;'|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=('<code class="doc-symbol doc-symbol-toc doc-symbol-class"></code>&nbsp;'|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 %}

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=('<code class="doc-symbol doc-symbol-toc doc-symbol-parameter"></code>&nbsp;'|safe if config.show_symbol_type_toc else '') + parameter.name,
+                    skip_inventory=config.skip_local_inventory,
                   ) %}
                   <code>{{ parameter.name }}</code>
                 {% endfilter %}
@@ -92,6 +93,7 @@ Context:
                 id=html_id ~ "(" ~ parameter.name ~ ")",
                 class="doc doc-heading doc-heading-parameter",
                 toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-parameter"></code>&nbsp;'|safe if config.show_symbol_type_toc else '') + parameter.name,
+                skip_inventory=config.skip_local_inventory,
               ) %}
               <b><code>{{ parameter.name }}</code></b>
             {% endfilter %}
@@ -139,6 +141,7 @@ Context:
                     id=html_id ~ "(" ~ parameter.name ~ ")",
                     class="doc doc-heading doc-heading-parameter",
                     toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-parameter"></code>&nbsp;'|safe if config.show_symbol_type_toc else '') + parameter.name,
+                    skip_inventory=config.skip_local_inventory,
                   ) %}
                   <code>{{ parameter.name }}</code>
                 {% endfilter %}

src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja

@@ -46,6 +46,7 @@ Context:
           id=html_id,
           class="doc doc-heading",
           toc_label=(('<code class="doc-symbol doc-symbol-toc doc-symbol-' + symbol_type + '"></code>&nbsp;')|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=(('<code class="doc-symbol doc-symbol-toc doc-symbol-' + symbol_type + '"></code>&nbsp;')|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 %}

src/mkdocstrings_handlers/python/templates/material/_base/module.html.jinja

@@ -39,6 +39,7 @@ Context:
           id=html_id,
           class="doc doc-heading",
           toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-module"></code>&nbsp;'|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=('<code class="doc-symbol doc-symbol-toc doc-symbol-module"></code>&nbsp;'|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 %}