Skip to content

Commit b06b0dc

Browse files
committed
Add skip_local_inventory docs
1 parent 63df2c8 commit b06b0dc

File tree

1 file changed

+63
-1
lines changed

1 file changed

+63
-1
lines changed

docs/usage/configuration/headings.md

Lines changed: 63 additions & 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

@@ -664,6 +664,68 @@ plugins:
664664
////
665665
///
666666

667+
668+
[](){#option-skip_local_inventory}
669+
## `skip_local_inventory`
670+
671+
- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
672+
<!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
673+
674+
Whether to not give objects local inventory entries and permalinks.
675+
676+
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.
677+
678+
```yaml title="in mkdocs.yml (global configuration)"
679+
plugins:
680+
- mkdocstrings:
681+
handlers:
682+
python:
683+
options:
684+
skip_local_inventory: false
685+
```
686+
687+
```md title="or in docs/some_page.md (local configuration)"
688+
::: path.to.module
689+
options:
690+
skip_local_inventory: true
691+
```
692+
693+
/// admonition | Preview
694+
type: preview
695+
696+
697+
//// tab | With `skip_local_inventory`
698+
699+
```md exec="on"
700+
::: bisect.bisect_left
701+
options:
702+
heading_level: 3
703+
skip_local_inventory: false
704+
show_docstring_description: false
705+
```
706+
707+
Notice how [`bisect.bisect_left`][] now points to the section above.
708+
709+
////
710+
711+
//// tab | Without `skip_local_inventory`
712+
713+
```md exec="on"
714+
::: bisect.bisect_right
715+
inventories:
716+
- https://docs.python.org/3/objects.inv
717+
options:
718+
heading_level: 3
719+
skip_local_inventory: true
720+
show_docstring_description: false
721+
```
722+
723+
Notice how [`bisect.bisect_right`][] points to the original Python documentation.
724+
725+
////
726+
727+
///
728+
667729
[](){#option-toc_label}
668730
## `toc_label`
669731

0 commit comments

Comments
 (0)