docs: Update docs from insiders

viktorlashchuk · viktorlashchuk · commit 738fa20b0672 · 2024-09-03T19:13:38.000+02:00
diff --git a/docs/insiders/changelog.md b/docs/insiders/changelog.md
@@ -2,6 +2,32 @@
 
 ## mkdocstrings-python Insiders
 
+### 1.8.3 <small>June 19, 2024</small> { id="1.8.3" }
+
+- Update code for Griffe 0.46+ to avoid deprecation warnings
+
+### 1.8.2 <small>May 09, 2024</small> { id="1.8.2" }
+
+- Don't render cross-refs for default values when signatures aren't separated
+
+### 1.8.1 <small>April 19, 2024</small> { id="1.8.1" }
+
+- Render enumeration instance name instead of just "value", allowing proper cross-reference
+
+### 1.8.0 <small>March 24, 2024</small> { id="1.8.0" }
+
+- [Annotations modernization][modernize_annotations]
+
+### 1.7.0 <small>March 24, 2024</small> { id="1.7.0" }
+
+- [Class inheritance diagrams with Mermaid][show_inheritance_diagram]
+
+### 1.6.0 <small>January 30, 2024</small> { id="1.6.0" }
+
+- Render cross-references to parameters documentation in signatures and attribute values.
+- Add [`parameter_headings`][parameter_headings] option to render headings for parameters (enabling permalinks and ToC/inventory entries).
+- Render cross-references for default parameter values in signatures.
+
 ### 1.5.1 <small>September 12, 2023</small> { id="1.5.1" }
 
 - Prevent empty auto-summarized Methods section.
diff --git a/docs/insiders/goals.yml b/docs/insiders/goals.yml
@@ -16,9 +16,24 @@ goals:
       since: 2023/08/20
     - name: Automatic rendering of function signature overloads
       since: 2023/09/05
+    - name: Parameter headings
+      ref: /usage/configuration/headings/#parameter_headings
+      since: 2024/01/30
+    - name: Automatic cross-references to parameters
+      ref: /usage/configuration/headings/#parameter_headings
+      since: 2024/01/30
+    - name: Automatic cross-references for default parameter values in signatures
+      since: 2024/01/30
   1500:
     name: HyperLamp Navigation Tips
-    features: []
+    features:
+    - name: Class inheritance diagrams with Mermaid
+      ref: /usage/configuration/general/#show_inheritance_diagram
+      since: 2024/03/24
+    - name: Annotations modernization
+      ref: /usage/configuration/signatures/#modernize_annotations
+      since: 2024/03/24
   2000:
     name: FusionDrive Ejection Configuration
-    features: []
+    features:
+    - name: Relative cross-references
diff --git a/docs/snippets/package/__init__.py b/docs/snippets/package/__init__.py
@@ -0,0 +1,19 @@
+from importlib import metadata
+
+def get_version(dist: str = "mkdocstrings-python") -> str:
+    """Get version of the given distribution.
+
+    Parameters:
+        dist: A distribution name.
+
+    Returns:
+        A version number.
+    """
+    try:
+        return metadata.version(dist)
+    except metadata.PackageNotFoundError:
+        return "0.0.0"
+
+
+current_version: str = get_version(dist="mkdocstrings-python")
+"""Current package version."""
diff --git a/docs/snippets/package/modern.py b/docs/snippets/package/modern.py
@@ -0,0 +1,3 @@
+from typing import Optional, Union, List
+
+example: Optional[Union[int, List[int]]] = None
diff --git a/docs/usage/configuration/general.md b/docs/usage/configuration/general.md
@@ -92,6 +92,91 @@ plugins:
 ////
 ///
 
+## `show_inheritance_diagram`
+
+[:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } &mdash;
+[:octicons-tag-24: Insiders 1.7.0](../../insiders/changelog.md#1.7.0)
+
+- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
+<!-- - **:octicons-project-template-24: Template :material-null:** (contained in [`class.html`][class template]) -->
+
+Show the inheritance diagram of a class using [Mermaid](https://mermaid.js.org/).
+
+With this option enabled, an inheritance diagram (as a flowchart)
+will be displayed after a class signature.
+Each node will act as a cross-reference
+and will bring you to the relevant class' documentation
+when clicking on it.
+
+It should work out of the box with [Material for MkDocs][].
+For other themes, you must include Mermaid's Javascript code manually:
+
+```yaml title="mkdocs.yml"
+extra_javascript:
+- https://unpkg.com/mermaid@10.9.0/dist/mermaid.min.js
+```
+
+```yaml title="in mkdocs.yml (global configuration)"
+plugins:
+- mkdocstrings:
+    handlers:
+      python:
+        options:
+          show_inheritance_diagram: true
+```
+
+```md title="or in docs/some_page.md (local configuration)"
+::: path.to.object
+    options:
+      show_inheritance_diagram: false
+```
+
+/// admonition | Preview
+    type: preview
+
+With the following classes:
+
+```python
+class SuperAbstract:
+    """Super abstract class."""
+class Mixin1:
+    """Mixin 1."""
+class Abstract(SuperAbstract, Mixin1):
+    """Abstract class."""
+class Mixin2A:
+    """Mixin 2A."""
+class Mixin2B(Mixin2A):
+    """Mixin 2B."""
+class Concrete(Abstract, Mixin2B):
+    """Concrete class."""
+class SuperConcrete(Concrete):
+    """Super concrete class."""
+```
+
+The diagram for `SuperConcrete` will look like this:
+
+```mermaid
+flowchart TD
+SuperConcrete[SuperConcrete]
+Concrete[Concrete]
+Abstract[Abstract]
+SuperAbstract[SuperAbstract]
+Mixin1[Mixin1]
+Mixin2B[Mixin2B]
+Mixin2A[Mixin2A]
+
+Concrete --> SuperConcrete
+Abstract --> Concrete
+SuperAbstract --> Abstract
+Mixin1 --> Abstract
+Mixin2B --> Concrete
+Mixin2A --> Mixin2B
+```
+
+*Nodes are not clickable in this example
+because these classes do not exist in our documentation.*
+///
+
 ## `show_source`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
diff --git a/docs/usage/configuration/headings.md b/docs/usage/configuration/headings.md
@@ -57,6 +57,129 @@ plugins:
 ////
 ///
 
+## `parameter_headings`
+
+[:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } &mdash;
+[:octicons-tag-24: Insiders 1.6.0](../../insiders/changelog.md#1.6.0)
+
+- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
+<!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
+
+Whether to render headings for function/method parameters.
+
+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.
+The permalink and inventory entry allow cross-references
+from internal and external pages.
+
+The identifier used in the permalink and inventory is of the following form:
+`path.to.function(param_name)`. To manually cross-reference a parameter,
+you can therefore use this Markdown syntax:
+
+```md
+- Class parameter: [`param`][package.module.Class(param)]
+- Method parameter: [`param`][package.module.Class.method(param)]
+- Function parameter: [`param`][package.module.function(param)]
+- Variadic positional parameters: [`*args`][package.module.function(*args)]
+- Variadic keyword parameters: [`**kwargs`][package.module.function(**kwargs)]
+```
+
+Enabling this option along with [`signature_crossrefs`][] will automatically
+render cross-references to parameters in class/function/method signatures
+and attributes values.
+
+```yaml title="in mkdocs.yml (global configuration)"
+plugins:
+- mkdocstrings:
+    handlers:
+      python:
+        options:
+          parameter_headings: false
+```
+
+```md title="or in docs/some_page.md (local configuration)"
+::: path.to.module
+    options:
+      parameter_headings: true
+```
+
+/// admonition | Preview: Cross-references
+    type: preview
+
+```md exec="on"
+::: package.get_version
+    options:
+      heading_level: 3
+      parameter_headings: true
+      docstring_section_style: list
+
+::: package.current_version
+    options:
+      heading_level: 3
+      line_length: 100
+```
+
+///
+
+/// admonition | Preview: Parameter sections
+    type: preview
+
+//// tab | Table style
+```md exec="on"
+::: package.get_version
+    options:
+      heading_level: 3
+      show_root_heading: false
+      show_root_toc_entry: false
+      parameter_headings: true
+      docstring_section_style: table
+      show_docstring_returns: false
+      show_docstring_description: false
+```
+////
+
+//// tab | List style
+```md exec="on"
+::: package.get_version
+    options:
+      heading_level: 3
+      show_root_heading: false
+      show_root_toc_entry: false
+      parameter_headings: true
+      docstring_section_style: list
+      show_docstring_returns: false
+      show_docstring_description: false
+```
+////
+
+//// tab | Spacy style
+```md exec="on"
+::: package.get_version
+    options:
+      heading_level: 3
+      show_root_heading: false
+      show_root_toc_entry: false
+      parameter_headings: true
+      docstring_section_style: spacy
+      show_docstring_returns: false
+      show_docstring_description: false
+```
+////
+///
+
+/// admonition | Preview: Table of contents (with symbol types)
+    type: preview
+
+<code class="doc-symbol doc-symbol-toc doc-symbol-function"></code> get_version<br>
+<code class="doc-symbol doc-symbol-toc doc-symbol-parameter" style="margin-left: 16px;"></code> dist
+
+To customize symbols, see [Customizing symbol types](../customization.md/#symbol-types).
+
+///
+
 ## `show_root_heading`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
diff --git a/docs/usage/configuration/signatures.md b/docs/usage/configuration/signatures.md
@@ -193,6 +193,93 @@ plugins:
 ////
 ///
 
+## `modernize_annotations`
+
+[:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } &mdash;
+[:octicons-tag-24: Insiders 1.8.0](../../insiders/changelog.md#1.8.0) &mdash;
+**This feature also requires 
+[Griffe Insiders](https://mkdocstrings.github.io/griffe/insiders/)
+to be installed.**
+
+- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
+<!-- - **:octicons-project-template-24: Template :material-null:** (contained in [`class.html`][class template]) -->
+
+Modernize annotations with latest features and PEPs of the Python language.
+
+The Python language keeps evolving, and often library developers
+must continue to support a few minor versions of Python.
+Therefore they cannot use some features that were introduced
+in the latest versions.
+
+Yet this doesn't mean they can't enjoy latest features in their docs:
+Griffe allows to "modernize" expressions, for example
+by replacing `typing.Union` with [PEP 604][pep-604] type unions `|`.
+Thanks to this, mkdocstrings' Python handler
+can automatically transform type annotations into their modern equivalent.
+This improves consistency in your docs, and shows users
+how to use your code with the latest features of the language.
+
+[pep-604]: https://peps.python.org/pep-0604/
+
+Modernizations applied:
+
+- `typing.Dict[A, B]` becomes `dict[A, B]`
+- `typing.List[A]` becomes `list[A]`
+- `typing.Set[A]` becomes `set[A]`
+- `typing.Tuple[A]` becomes `tuple[A]`
+- `typing.Union[A, B]` becomes `A | B`
+- `typing.Optional[A]` becomes `A | None`
+
+```yaml title="in mkdocs.yml (global configuration)"
+plugins:
+- mkdocstrings:
+    handlers:
+      python:
+        options:
+          modernize_annotations: true
+```
+
+```md title="or in docs/some_page.md (local configuration)"
+::: path.to.object
+    options:
+      modernize_annotations: false
+```
+
+/// admonition | Preview
+    type: preview
+
+```python
+--8<-- "docs/snippets/package/modern.py"
+```
+
+//// tab | Unchanged annotations
+
+```md exec="on"
+::: package.modern.example
+    options:
+      modernize_annotations: false
+      show_symbol_type_heading: false
+      show_labels: false
+```
+
+////
+
+//// tab | Modernized annotations
+
+```md exec="on"
+::: package.modern.example
+    options:
+      modernize_annotations: true
+      show_symbol_type_heading: false
+      show_labels: false
+```
+
+////
+
+///
+
+
+
 ## `show_signature`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
diff --git a/docs/usage/customization.md b/docs/usage/customization.md
diff --git a/mkdocs.yml b/mkdocs.yml

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+from typing import Optional, Union, List`
	`2`	`+`
	`3`	`+example: Optional[Union[int, List[int]]] = None`