mkdocstrings-python 1.10.9__tar.gz → 1.11.1__tar.gz

{mkdocstrings_python-1.10.9 → mkdocstrings_python-1.11.1}/CHANGELOG.md

@@ -5,6 +5,22 @@ The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)
 and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).
 
 <!-- insertion marker -->
+## [1.11.1](https://github.com/mkdocstrings/python/releases/tag/1.11.1) - 2024-09-03
+
+<small>[Compare with 1.11.0](https://github.com/mkdocstrings/python/compare/1.11.0...1.11.1)</small>
+
+### Code Refactoring
+
+- Prepare `relative_crossrefs` and `scoped_crossrefs` insiders features ([dd8b014](https://github.com/mkdocstrings/python/commit/dd8b014a8ab3decc31d4b08bc22fe68577e1a02c) by Timothée Mazzucotelli).
+
+## [1.11.0](https://github.com/mkdocstrings/python/releases/tag/1.11.0) - 2024-09-03
+
+<small>[Compare with 1.10.9](https://github.com/mkdocstrings/python/compare/1.10.9...1.11.0)</small>
+
+### Features
+
+- Hook into autorefs to provide context around cross-ref errors ([bb4be5b](https://github.com/mkdocstrings/python/commit/bb4be5be1b85be50f46c7889231a2d4a3bd05165) by Timothée Mazzucotelli).
+
 ## [1.10.9](https://github.com/mkdocstrings/python/releases/tag/1.10.9) - 2024-08-30
 
 <small>[Compare with 1.10.8](https://github.com/mkdocstrings/python/compare/1.10.8...1.10.9)</small>

{mkdocstrings_python-1.10.9 → mkdocstrings_python-1.11.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: mkdocstrings-python
-Version: 1.10.9
+Version: 1.11.1
 Summary: A Python handler for mkdocstrings.
 Author-Email: =?utf-8?q?Timoth=C3=A9e_Mazzucotelli?= <dev@pawamoy.fr>
 License: ISC
@@ -28,8 +28,8 @@ Project-URL: Discussions, https://github.com/mkdocstrings/python/discussions
 Project-URL: Gitter, https://gitter.im/mkdocstrings/python
 Project-URL: Funding, https://github.com/sponsors/pawamoy
 Requires-Python: >=3.8
-Requires-Dist: mkdocstrings>=0.25
-Requires-Dist: mkdocs-autorefs>=1.0
+Requires-Dist: mkdocstrings>=0.26
+Requires-Dist: mkdocs-autorefs>=1.2
 Requires-Dist: griffe>=0.49
 Description-Content-Type: text/markdown
 

{mkdocstrings_python-1.10.9 → mkdocstrings_python-1.11.1}/docs/insiders/changelog.md

@@ -2,6 +2,37 @@
 
 ## mkdocstrings-python Insiders
 
+### 1.9.0 <small>September 03, 2024</small> { id="1.9.0" }
+
+- [Relative cross-references][relative_crossrefs]
+- [Scoped cross-references][scoped_crossrefs]
+
+### 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.

mkdocstrings_python-1.11.1/docs/insiders/goals.yml

@@ -0,0 +1,44 @@
+goals:
+  500:
+    name: PlasmaVac User Guide
+    features:
+    - name: Cross-references for type annotations in signatures
+      ref: /usage/configuration/signatures/#signature_crossrefs
+      since: 2023/05/10
+    - name: Symbol types in headings and table of contents
+      ref: /usage/configuration/headings/#show_symbol_type_toc
+      since: 2023/06/04
+  1000:
+    name: GraviFridge Fluid Renewal
+    features:
+    - name: Auto-summary of object members
+      ref: /usage/configuration/members/#summary
+      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:
+    - 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:
+    - name: Relative cross-references
+      ref: /usage/configuration/docstrings/#relative_crossrefs
+      since: 2024/09/03
+    - name: Scoped cross-references
+      ref: /usage/configuration/docstrings/#scoped_crossrefs
+      since: 2024/09/03

mkdocstrings_python-1.11.1/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."""

mkdocstrings_python-1.11.1/docs/snippets/package/modern.py

@@ -0,0 +1,3 @@
+from typing import Optional, Union, List
+
+example: Optional[Union[int, List[int]]] = None

{mkdocstrings_python-1.10.9 → mkdocstrings_python-1.11.1}/docs/usage/configuration/docstrings.md

@@ -317,6 +317,226 @@ class Thing:
 ////
 ///
 
+## `relative_crossrefs`
+
+[:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } —
+[:octicons-tag-24: Insiders 1.9.0](../../insiders/changelog.md#1.9.0)
+
+- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
+<!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
+
+Whether to enable the relative-crossref syntax.
+
+The relative-crossref syntax lets you reference the current object or its parent by prefixing a crossref identifier with dots. For example, to cross-reference the current object's `name` member, you can write `[link to name attribute][.name]`. The "current object" is the object containing the docstring being rendered.
+
+
+```yaml title="in mkdocs.yml (global configuration)"
+plugins:
+- mkdocstrings:
+    handlers:
+      python:
+        options:
+          relative_crossrefs: false
+```
+
+```md title="or in docs/some_page.md (local configuration)"
+::: path.to.module
+    options:
+      relative_crossrefs: true
+```
+
+/// admonition | Examples
+    type: preview
+
+```python title="pkg/module.py"
+"""Summary.
+
+- Link to [`module`][.].
+- Link to [`module_attribute`][.module_attribute].
+- Link to [`Class`][.Class].
+- Link to [`class_attribute`][.Class.class_attribute].
+- Link to [`instance_attribute`][.Class.instance_attribute].
+- Link to [`method`][.Class.method].
+"""
+
+module_attribute = 0
+"""Summary.
+
+- Link to [`module`][..].
+- Link to [`module_attribute`][.].
+- Link to [`Class`][..Class].
+- Link to [`class_attribute`][..Class.class_attribute].
+- Link to [`instance_attribute`][..Class.instance_attribute].
+- Link to [`method`][..Class.method].
+"""
+
+class Class:
+    """Summary.
+
+    - Link to [`module`][..].
+    - Link to [`module_attribute`][..module_attribute].
+    - Link to [`Class`][.].
+    - Link to [`class_attribute`][.class_attribute].
+    - Link to [`instance_attribute`][.instance_attribute].
+    - Link to [`method`][.method].
+    """
+
+    class_attribute = 0
+    """Summary.
+
+    - Link to [`module`][...].
+    - Link to [`module_attribute`][...module_attribute].
+    - Link to [`Class`][..].
+    - Link to [`class_attribute`][.].
+    - Link to [`instance_attribute`][..instance_attribute].
+    - Link to [`method`][..method].
+    """
+
+    def __init__(self):
+        """Summary.
+
+        - Link to [`module`][...].
+        - Link to [`module_attribute`][...module_attribute].
+        - Link to [`Class`][..].
+        - Link to [`class_attribute`][..class_attribute].
+        - Link to [`instance_attribute`][..instance_attribute].
+        - Link to [`method`][..method].
+        """
+        self.instance_attribute = 0
+        """Summary.
+
+        - Link to [`module`][...].
+        - Link to [`module_attribute`][...module_attribute].
+        - Link to [`Class`][..].
+        - Link to [`class_attribute`][..class_attribute].
+        - Link to [`instance_attribute`][.].
+        - Link to [`method`][..method].
+        """
+
+    def method(self):
+        """Summary.
+
+        - Link to [`module`][...].
+        - Link to [`module_attribute`][...module_attribute].
+        - Link to [`Class`][..].
+        - Link to [`class_attribute`][..class_attribute].
+        - Link to [`instance_attribute`][..instance_attribute].
+        - Link to [`method`][.].
+        """
+```
+
+///
+
+
+## `scoped_crossrefs`
+
+[:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } &mdash;
+[:octicons-tag-24: Insiders 1.9.0](../../insiders/changelog.md#1.9.0)
+
+- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
+<!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
+
+Whether to enable scoped cross-references.
+
+With scoped cross-references, you can write identifiers as if you wanted to access them from the current object's scope. The scoping rules do not exactly match Python's: you can reference members and siblings too, without prefixing with `self.` or `cls.`.
+
+The following order is applied when resolving a name in a given scope:
+
+1. member of the current object
+2. parent class
+3. repeat 1-2 within parent's scope
+
+In practice, it means that the name is first looked up in members, then it is compared against the parent name (only if it's a class), then it is looked up in siblings. It continues climbing up the object tree until there's no parent, in which case it raises a name resolution error.
+
+Cross-referencing an imported object will directly link to this object if the objects inventory of the project it comes from was [loaded][import]. You won't be able to cross-reference it within your own documentation with scoped references, if you happen to be rendering this external object too. In that case, you can use an absolute reference or a [relative][relative_crossrefs] one instead.
+
+Another limitation is that you won't be able to reference an external package if its name can be resolved in the current object's scope.
+
+```yaml title="in mkdocs.yml (global configuration)"
+plugins:
+- mkdocstrings:
+    handlers:
+      python:
+        options:
+          scoped_crossrefs: false
+```
+
+```md title="or in docs/some_page.md (local configuration)"
+::: path.to.module
+    options:
+      scoped_crossrefs: true
+```
+
+/// admonition | Examples
+    type: preview
+
+```python title="pkg/module.py"
+"""Summary.
+
+- Link to [`module_attribute`][module_attribute].
+- Link to [`Class`][Class].
+- Link to [`class_attribute`][Class.class_attribute].
+- Link to [`instance_attribute`][Class.instance_attribute].
+- Link to [`method`][Class.method].
+"""
+
+module_attribute = 0
+"""Summary.
+
+- Link to [`Class`][Class].
+- Link to [`class_attribute`][Class.class_attribute].
+- Link to [`instance_attribute`][Class.instance_attribute].
+- Link to [`method`][Class.method].
+"""
+
+class Class:
+    """Summary.
+
+    - Link to [`module_attribute`][module_attribute].
+    - Link to [`class_attribute`][class_attribute].
+    - Link to [`instance_attribute`][instance_attribute].
+    - Link to [`method`][method].
+    """
+
+    class_attribute = 0
+    """Summary.
+
+    - Link to [`module_attribute`][module_attribute].
+    - Link to [`Class`][Class].
+    - Link to [`instance_attribute`][instance_attribute].
+    - Link to [`method`][method].
+    """
+
+    def __init__(self):
+        """Summary.
+
+        - Link to [`module_attribute`][module_attribute].
+        - Link to [`Class`][Class].
+        - Link to [`class_attribute`][class_attribute].
+        - Link to [`instance_attribute`][instance_attribute].
+        - Link to [`method`][method].
+        """
+        self.instance_attribute = 0
+        """Summary.
+
+        - Link to [`module_attribute`][module_attribute].
+        - Link to [`Class`][Class].
+        - Link to [`class_attribute`][class_attribute].
+        - Link to [`method`][method].
+        """
+
+    def method(self):
+        """Summary.
+
+        - Link to [`module_attribute`][module_attribute].
+        - Link to [`Class`][Class].
+        - Link to [`class_attribute`][class_attribute].
+        - Link to [`instance_attribute`][instance_attribute].
+        """
+```
+
+///
+
 ## `show_if_no_docstring`
 
 - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**

{mkdocstrings_python-1.10.9 → mkdocstrings_python-1.11.1}/docs/usage/configuration/general.md

@@ -92,6 +92,91 @@ plugins:
 ////
 ///
 
+## `show_inheritance_diagram`
+
+[:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } —
+[: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" }**

{mkdocstrings_python-1.10.9 → mkdocstrings_python-1.11.1}/docs/usage/configuration/headings.md

@@ -57,6 +57,129 @@ plugins:
 ////
 ///
 
+## `parameter_headings`
+
+[:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } —
+[: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" }**

{mkdocstrings_python-1.10.9 → mkdocstrings_python-1.11.1}/docs/usage/configuration/signatures.md

@@ -193,6 +193,93 @@ plugins:
 ////
 ///
 
+## `modernize_annotations`
+
+[:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } —
+[:octicons-tag-24: Insiders 1.8.0](../../insiders/changelog.md#1.8.0) —
+**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" }**