Skip to content

Commit e82c24f

Browse files
bswckbswck
authored
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
1 parent baf3fac commit e82c24f

File tree

10 files changed

+85
-6
lines changed

10 files changed

+85
-6
lines changed

‎docs/usage/configuration/general.md

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -494,3 +494,63 @@ def some_function():
494494
<p>Docstring of the function.</p>
495495
////
496496
///
497+
498+
[](){#option-skip_local_inventory}
499+
## `skip_local_inventory`
500+
501+
- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
502+
<!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
503+
504+
Whether to skip registering symbols in the objects inventory.
505+
506+
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).
507+
508+
```yaml title="in mkdocs.yml (global configuration)"
509+
plugins:
510+
- mkdocstrings:
511+
handlers:
512+
python:
513+
options:
514+
skip_local_inventory: false
515+
```
516+
517+
```md title="or in docs/some_page.md (local configuration)"
518+
::: path.to.module
519+
options:
520+
skip_local_inventory: true
521+
```
522+
523+
/// admonition | Preview
524+
type: preview
525+
526+
527+
//// tab | Without `skip_local_inventory`
528+
529+
```md exec="on"
530+
::: bisect.bisect_left
531+
options:
532+
heading_level: 3
533+
skip_local_inventory: false
534+
show_docstring_description: false
535+
```
536+
537+
Notice how [`bisect.bisect_left`][] now points to the section above.
538+
539+
////
540+
541+
//// tab | With `skip_local_inventory`
542+
543+
```md exec="on"
544+
::: bisect.bisect_right
545+
inventories:
546+
- https://docs.python.org/3/objects.inv
547+
options:
548+
heading_level: 3
549+
skip_local_inventory: true
550+
show_docstring_description: false
551+
```
552+
553+
Notice how [`bisect.bisect_right`][] points to the original Python documentation.
554+
555+
////
556+
///

‎docs/usage/configuration/headings.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -88,7 +88,7 @@ With this option enabled, each function/method parameter
8888
(including parameters of `__init__` methods merged in their parent class
8989
with the [`merge_init_into_class`][] option)
9090
gets a permalink, an entry in the Table of Contents,
91-
and an entry in the generated objects inventory.
91+
and an entry in the generated objects inventory (unless [`skip_local_inventory`][] is enabled).
9292
The permalink and inventory entry allow cross-references
9393
from internal and external pages.
9494

‎pyproject.toml

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ classifiers = [
3131
"Typing :: Typed",
3232
]
3333
dependencies = [
34-
"mkdocstrings>=0.28.3",
34+
"mkdocstrings>=0.30",
3535
"mkdocs-autorefs>=1.4",
3636
"griffe>=1.6.2",
3737
"typing-extensions>=4.0; python_version < '3.11'",

‎src/mkdocstrings_handlers/python/_internal/config.py

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -865,6 +865,14 @@ class PythonInputOptions:
865865
),
866866
] = False
867867

868+
skip_local_inventory: Annotated[
869+
bool,
870+
_Field(
871+
group="general",
872+
description="Whether to prevent objects from being registered in the local objects inventory.",
873+
),
874+
] = False
875+
868876
signature_crossrefs: Annotated[
869877
bool,
870878
_Field(

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@ Context:
4040
id=html_id,
4141
class="doc doc-heading",
4242
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),
43+
skip_inventory=config.skip_local_inventory,
4344
) %}
4445

4546
{% block heading scoped %}
@@ -93,6 +94,7 @@ Context:
9394
id=html_id,
9495
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),
9596
hidden=True,
97+
skip_inventory=config.skip_local_inventory,
9698
) %}
9799
{% endfilter %}
98100
{% endif %}

‎src/mkdocstrings_handlers/python/templates/material/_base/children.html.jinja

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -45,7 +45,7 @@ Context:
4545
) %}
4646
{% if attributes %}
4747
{% if config.show_category_heading %}
48-
{% filter heading(heading_level, id=html_id ~ "-attributes") %}Attributes{% endfilter %}
48+
{% filter heading(heading_level, id=html_id ~ "-attributes", skip_inventory=config.skip_local_inventory) %}Attributes{% endfilter %}
4949
{% endif %}
5050
{% with heading_level = heading_level + extra_level %}
5151
{% for attribute in attributes|order_members(config.members_order, members_list) %}
@@ -65,7 +65,7 @@ Context:
6565
) %}
6666
{% if classes %}
6767
{% if config.show_category_heading %}
68-
{% filter heading(heading_level, id=html_id ~ "-classes") %}Classes{% endfilter %}
68+
{% filter heading(heading_level, id=html_id ~ "-classes", skip_inventory=config.skip_local_inventory) %}Classes{% endfilter %}
6969
{% endif %}
7070
{% with heading_level = heading_level + extra_level %}
7171
{% for class in classes|order_members(config.members_order, members_list) %}
@@ -85,7 +85,7 @@ Context:
8585
) %}
8686
{% if functions %}
8787
{% if config.show_category_heading %}
88-
{% filter heading(heading_level, id=html_id ~ "-functions") %}Functions{% endfilter %}
88+
{% filter heading(heading_level, id=html_id ~ "-functions", skip_inventory=config.skip_local_inventory) %}Functions{% endfilter %}
8989
{% endif %}
9090
{% with heading_level = heading_level + extra_level %}
9191
{% for function in functions|order_members(config.members_order, members_list) %}
@@ -108,7 +108,7 @@ Context:
108108
) %}
109109
{% if modules %}
110110
{% if config.show_category_heading %}
111-
{% filter heading(heading_level, id=html_id ~ "-modules") %}Modules{% endfilter %}
111+
{% filter heading(heading_level, id=html_id ~ "-modules", skip_inventory=config.skip_local_inventory) %}Modules{% endfilter %}
112112
{% endif %}
113113
{% with heading_level = heading_level + extra_level %}
114114
{% for module in modules|order_members("alphabetical", members_list) %}

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@ Context:
3939
id=html_id,
4040
class="doc doc-heading",
4141
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),
42+
skip_inventory=config.skip_local_inventory,
4243
) %}
4344

4445
{% block heading scoped %}
@@ -112,6 +113,7 @@ Context:
112113
id=html_id,
113114
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),
114115
hidden=True,
116+
skip_inventory=config.skip_local_inventory,
115117
) %}
116118
{% endfilter %}
117119
{% endif %}

‎src/mkdocstrings_handlers/python/templates/material/_base/docstring/parameters.html.jinja

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@ Context:
4343
id=html_id ~ "(" ~ parameter.name ~ ")",
4444
class="doc doc-heading doc-heading-parameter",
4545
toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-parameter"></code>&nbsp;'|safe if config.show_symbol_type_toc else '') + parameter.name,
46+
skip_inventory=config.skip_local_inventory,
4647
) %}
4748
<code>{{ parameter.name }}</code>
4849
{% endfilter %}
@@ -92,6 +93,7 @@ Context:
9293
id=html_id ~ "(" ~ parameter.name ~ ")",
9394
class="doc doc-heading doc-heading-parameter",
9495
toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-parameter"></code>&nbsp;'|safe if config.show_symbol_type_toc else '') + parameter.name,
96+
skip_inventory=config.skip_local_inventory,
9597
) %}
9698
<b><code>{{ parameter.name }}</code></b>
9799
{% endfilter %}
@@ -139,6 +141,7 @@ Context:
139141
id=html_id ~ "(" ~ parameter.name ~ ")",
140142
class="doc doc-heading doc-heading-parameter",
141143
toc_label=('<code class="doc-symbol doc-symbol-toc doc-symbol-parameter"></code>&nbsp;'|safe if config.show_symbol_type_toc else '') + parameter.name,
144+
skip_inventory=config.skip_local_inventory,
142145
) %}
143146
<code>{{ parameter.name }}</code>
144147
{% endfilter %}

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,7 @@ Context:
4646
id=html_id,
4747
class="doc doc-heading",
4848
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),
49+
skip_inventory=config.skip_local_inventory,
4950
) %}
5051

5152
{% block heading scoped %}
@@ -110,6 +111,7 @@ Context:
110111
id=html_id,
111112
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),
112113
hidden=True,
114+
skip_inventory=config.skip_local_inventory,
113115
) %}
114116
{% endfilter %}
115117
{% endif %}

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,7 @@ Context:
3939
id=html_id,
4040
class="doc doc-heading",
4141
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),
42+
skip_inventory=config.skip_local_inventory,
4243
) %}
4344

4445
{% block heading scoped %}
@@ -76,6 +77,7 @@ Context:
7677
id=html_id,
7778
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),
7879
hidden=True,
80+
skip_inventory=config.skip_local_inventory,
7981
) %}
8082
{% endfilter %}
8183
{% endif %}

0 commit comments

Comments
 (0)