feat: Add skip_local_inventory option to prevent objects from being registered in the local objects inventory

Issue-296: #296
Issue-mkdocstrings-671: mkdocstrings/mkdocstrings#671
PR-297: #297

Author: bswck

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 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.
+
+////
+///

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

@@ -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'",

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 prevent objects from being registered in the local objects inventory.",
+        ),
+    ] = 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 %}