mkdocstrings-python 1.18.2__tar.gz → 1.19.0__tar.gz

{mkdocstrings_python-1.18.2 → mkdocstrings_python-1.19.0}/CHANGELOG.md

@@ -5,6 +5,24 @@ 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.19.0](https://github.com/mkdocstrings/python/releases/tag/1.19.0) - 2025-11-10
+
+<small>[Compare with 1.18.2](https://github.com/mkdocstrings/python/compare/1.18.2...1.19.0)</small>
+
+### Features
+
+- Release scoped and relative cross-references ([872afc5](https://github.com/mkdocstrings/python/commit/872afc584f33f50a133472afdc9355734a5e51ec) by Timothée Mazzucotelli).
+- Release `__all__` ordering feature ([84aaebc](https://github.com/mkdocstrings/python/commit/84aaebcb4991c0245bf7ca8d7024c9d04942b0c1) by Timothée Mazzucotelli).
+- Release public filter feature ([3be14cc](https://github.com/mkdocstrings/python/commit/3be14cc07bc9429d7ce01c748d825e2db1559212) by Timothée Mazzucotelli).
+- Release backlinks feature ([ae7cc2d](https://github.com/mkdocstrings/python/commit/ae7cc2d7d8ea5711d8ce06620edd534a3e2b47aa) by Timothée Mazzucotelli).
+- Release expression modernization feature ([dbadd1e](https://github.com/mkdocstrings/python/commit/dbadd1e898bb2e67515077d152890bdbbf0b3eb1) by Timothée Mazzucotelli).
+- Release visually-lighter admonitions for source code blocks ([fdaeb48](https://github.com/mkdocstrings/python/commit/fdaeb48a0f2208bafd14f2f7ead42bca37bea665) by Timothée Mazzucotelli).
+- Release inheritance diagram features ([669b42e](https://github.com/mkdocstrings/python/commit/669b42ebd7c154c81764fa98c052cf857f7aa406) by Timothée Mazzucotelli).
+
+### Code Refactoring
+
+- Update code base for Python 3.10 ([b696ed2](https://github.com/mkdocstrings/python/commit/b696ed2224756472a3617fa3cc18b69d0418ed71) by Timothée Mazzucotelli).
+
 ## [1.18.2](https://github.com/mkdocstrings/python/releases/tag/1.18.2) - 2025-08-28
 
 <small>[Compare with 1.18.1](https://github.com/mkdocstrings/python/compare/1.18.1...1.18.2)</small>
@@ -487,9 +505,6 @@ Importing from submodules is now deprecated: the public API is fully exposed und
     - [`griffe-inherited-docstrings`](https://mkdocstrings.github.io/griffe-inherited-docstrings/), a Griffe extension for inheriting docstrings
     - [`griffe2md`](https://mkdocstrings.github.io/griffe2md/), a tool to output API docs to Markdown using Griffe
 
-    See the complete list of features and projects here:
-    https://pawamoy.github.io/insiders/#500-plasmavac-user-guide.
-
 ## [1.7.5](https://github.com/mkdocstrings/python/releases/tag/1.7.5) - 2023-11-21
 
 <small>[Compare with 1.7.4](https://github.com/mkdocstrings/python/compare/1.7.4...1.7.5)</small>

{mkdocstrings_python-1.18.2 → mkdocstrings_python-1.19.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocstrings-python
-Version: 1.18.2
+Version: 1.19.0
 Summary: A Python handler for mkdocstrings.
 Author-Email: =?utf-8?q?Timoth=C3=A9e_Mazzucotelli?= <dev@pawamoy.fr>
 License-Expression: ISC
@@ -10,7 +10,6 @@ Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
@@ -29,7 +28,7 @@ Project-URL: Issues, https://github.com/mkdocstrings/python/issues
 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.9
+Requires-Python: >=3.10
 Requires-Dist: mkdocstrings>=0.30
 Requires-Dist: mkdocs-autorefs>=1.4
 Requires-Dist: griffe>=1.13
@@ -43,7 +42,7 @@ Description-Content-Type: text/markdown
 [![ci](https://github.com/mkdocstrings/python/workflows/ci/badge.svg)](https://github.com/mkdocstrings/python/actions?query=workflow%3Aci)
 [![documentation](https://img.shields.io/badge/docs-mkdocs-708FCC.svg?style=flat)](https://mkdocstrings.github.io/python/)
 [![pypi version](https://img.shields.io/pypi/v/mkdocstrings-python.svg)](https://pypi.org/project/mkdocstrings-python/)
-[![gitter](https://badges.gitter.im/join%20chat.svg)](https://app.gitter.im/#/room/#python:gitter.im)
+[![gitter](https://img.shields.io/badge/matrix-chat-4DB798.svg?style=flat)](https://app.gitter.im/#/room/#mkdocstrings_python:gitter.im)
 
 ---
 
@@ -115,3 +114,8 @@ dependencies = [
 
 - **Source code display:** *mkdocstrings* can add a collapsible div containing the highlighted source code
   of the Python object.
+
+## Sponsors
+
+<!-- sponsors-start -->
+<!-- sponsors-end -->

{mkdocstrings_python-1.18.2 → mkdocstrings_python-1.19.0}/README.md

@@ -5,7 +5,7 @@
 [![ci](https://github.com/mkdocstrings/python/workflows/ci/badge.svg)](https://github.com/mkdocstrings/python/actions?query=workflow%3Aci)
 [![documentation](https://img.shields.io/badge/docs-mkdocs-708FCC.svg?style=flat)](https://mkdocstrings.github.io/python/)
 [![pypi version](https://img.shields.io/pypi/v/mkdocstrings-python.svg)](https://pypi.org/project/mkdocstrings-python/)
-[![gitter](https://badges.gitter.im/join%20chat.svg)](https://app.gitter.im/#/room/#python:gitter.im)
+[![gitter](https://img.shields.io/badge/matrix-chat-4DB798.svg?style=flat)](https://app.gitter.im/#/room/#mkdocstrings_python:gitter.im)
 
 ---
 
@@ -77,3 +77,8 @@ dependencies = [
 
 - **Source code display:** *mkdocstrings* can add a collapsible div containing the highlighted source code
   of the Python object.
+
+## Sponsors
+
+<!-- sponsors-start -->
+<!-- sponsors-end -->

{mkdocstrings_python-1.18.2 → mkdocstrings_python-1.19.0}/config/pytest.ini

@@ -10,6 +10,8 @@ testpaths =
 # action:message_regex:warning_class:module_regex:line
 filterwarnings =
   error
+  default::EncodingWarning
+  error::EncodingWarning:python
   # TODO: Remove once pytest-xdist 4 is released.
   ignore:.*rsyncdir:DeprecationWarning:xdist
   # TODO: Remove once mkdocstrings stops setting fallback function.

{mkdocstrings_python-1.18.2 → mkdocstrings_python-1.19.0}/docs/.overrides/main.html

@@ -1,13 +1,11 @@
 {% extends "base.html" %}
 
 {% block announce %}
-
-    <strong>Fund this project</strong> through
-    <a href="{{ 'insiders/#how-to-become-a-sponsor' | url }}"><strong>sponsorship</strong></a>
-    <span class="twemoji heart pulse">
-      {% include ".icons/octicons/heart-fill-16.svg" %}
-    </span> &mdash;
-
+  <strong>Fund this project</strong> through
+  <a href="https://github.com/sponsors/pawamoy"><strong>sponsorship</strong></a>
+  <span class="twemoji heart pulse">
+    {% include ".icons/octicons/heart-fill-16.svg" %}
+  </span> &mdash;
   Follow
   <strong>@pawamoy</strong> on
   <a rel="me" href="https://fosstodon.org/@pawamoy">

{mkdocstrings_python-1.18.2 → mkdocstrings_python-1.19.0}/docs/usage/configuration/docstrings.md

@@ -327,9 +327,6 @@ class Thing:
 [](){#option-relative_crossrefs}
 ## `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) -->
 
@@ -440,9 +437,6 @@ INFO: **There is an alternative, third-party Python handler that handles relativ
 [](){#option-scoped_crossrefs}
 ## `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) -->
 

{mkdocstrings_python-1.18.2 → mkdocstrings_python-1.19.0}/docs/usage/configuration/general.md

@@ -63,9 +63,6 @@ plugins:
 [](){#option-backlinks}
 ## `backlinks`
 
-[:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } —
-[:octicons-tag-24: Insiders 1.10.0](../../insiders/changelog.md#1.10.0)
-
 - **:octicons-package-24: Type <code><autoref identifier="typing.Literal" optional>Literal</autoref>["flat", "tree", False]</code> :material-equal: `False`{ title="default value" }**
 
 The `backlinks` option enables rendering of backlinks within your API documentation.
@@ -269,6 +266,143 @@ plugins:
 
 WARNING: **Packages are loaded only once.** When mkdocstrings-python collects data from a Python package (thanks to [Griffe](https://mkdocstrings.github.io/griffe/)), it collects *the entire package* and *caches it*. Next time an object from the same package is rendered, the package is retrieved from the cache and not collected again. The `force_inspection` option will therefore only have an effect the first time a package is collected, and will do nothing for objects rendered afterwards.
 
+[](){#option-inheritance_diagram_direction}
+## `inheritance_diagram_direction`
+
+The direction of the Mermaid chart presenting the inheritance diagram of a class, `TD` by default.
+
+```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:
+          inheritance_diagram_direction: TD
+```
+
+```md title="or in docs/some_page.md (local configuration)"
+::: path.to.object
+    options:
+      inheritance_diagram_direction: TD
+```
+
+/// 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."""
+```
+
+//// tab | `TD` (or `TB`)
+
+```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
+```
+
+////
+
+//// tab | `BT`
+
+```mermaid
+flowchart BT
+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
+```
+
+////
+
+//// tab | `RL`
+
+```mermaid
+flowchart RL
+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
+```
+
+////
+
+//// tab | `LR`
+
+```mermaid
+flowchart LR
+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
+```
+
+////
+///
+
 [](){#option-preload_modules}
 ## `preload_modules`
 
@@ -366,9 +500,6 @@ plugins:
 [](){#option-show_inheritance_diagram}
 ## `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]) -->
 

{mkdocstrings_python-1.18.2 → mkdocstrings_python-1.19.0}/docs/usage/configuration/headings.md

@@ -77,8 +77,6 @@ plugins:
 [](){#option-parameter_headings}
 ## `parameter_headings`
 
-[: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) -->
 
@@ -537,8 +535,6 @@ plugins:
 [](){#option-show_symbol_type_heading}
 ## `show_symbol_type_heading`
 
-[:octicons-tag-24: Insiders 1.1.0](../../insiders/changelog.md#1.1.0)
-
 - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
 <!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
 
@@ -602,8 +598,6 @@ plugins:
 [](){#option-show_symbol_type_toc}
 ## `show_symbol_type_toc`
 
-[:octicons-tag-24: Insiders 1.1.0](../../insiders/changelog.md#1.1.0)
-
 - **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
 <!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
 

{mkdocstrings_python-1.18.2 → mkdocstrings_python-1.19.0}/docs/usage/configuration/members.md

@@ -269,7 +269,7 @@ class Main(Base):
 
 The members ordering to use. Possible values:
 
-- `__all__` ([:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } — [:octicons-tag-24: Insiders 1.12.0](../../insiders/changelog.md#1.12.0)): Order according to `__all__` attributes. Since classes do not define `__all__` attributes, you can specify a second ordering method by using a list.
+- `__all__`: Order according to `__all__` attributes. Since classes do not define `__all__` attributes, you can specify a second ordering method by using a list.
 - `alphabetical`: Order by the members names.
 - `source`: Order members as they appear in the source file.
 
@@ -351,9 +351,6 @@ A list of filters, or `"public"`.
 
 [](){#option-filters-public}
 
-[:octicons-heart-fill-24:{ .pulse } Sponsors only](../../insiders/index.md){ .insiders } —
-[:octicons-tag-24: Insiders 1.11.0](../../insiders/changelog.md#1.11.0)
-
 The `public` filtering method will include only public objects: those added to the `__all__` attribute of modules, or not starting with a single underscore. Special methods and attributes ("dunder" methods/attributes, starting and ending with two underscores), like `__init__`, `__call__`, `__mult__`, etc., are always considered public.
 
 **List of filters**
@@ -577,8 +574,6 @@ package
 [](){#option-summary}
 ## `summary`
 
-[:octicons-tag-24: Insiders 1.2.0](../../insiders/changelog.md#1.2.0)
-
 - **:octicons-package-24: Type <code><autoref identifier="bool" optional>bool</autoref> | <autoref identifier="dict" optional>dict</autoref>[<autoref identifier="str" optional>str</autoref>, <autoref identifier="bool" optional>bool</autoref>]</code>  :material-equal: `False`{ title="default value" }**
 <!-- - **:octicons-project-template-24: Template :material-null:** (N/A) -->
 

{mkdocstrings_python-1.18.2 → mkdocstrings_python-1.19.0}/docs/usage/configuration/signatures.md

@@ -203,12 +203,6 @@ plugins:
 [](){#option-modernize_annotations}
 ## `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]) -->
 
@@ -289,6 +283,8 @@ plugins:
 [](){#option-overloads_only}
 ## `overloads_only`
 
+- **:octicons-package-24: Type [`bool`][] :material-equal: `False`{ title="default value" }**
+
 Whether to hide the implementation signature if the overloads are shown with [`show_overloads`][].
 
 ```yaml title="in mkdocs.yml (global configuration)"
@@ -297,7 +293,7 @@ plugins:
     handlers:
       python:
         options:
-          overloads_only: true
+          overloads_only: false
 ```
 
 ```md title="or in docs/some_page.md (local configuration)"
@@ -584,6 +580,8 @@ class SomeClass:
 [](){#option-show_overloads}
 ## `show_overloads`
 
+- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }**
+
 Whether to render function / method overloads.
 
 ```yaml title="in mkdocs.yml (global configuration)"
@@ -633,8 +631,6 @@ Function docstring.
 [](){#option-signature_crossrefs}
 ## `signature_crossrefs`
 
-[:octicons-tag-24: Insiders 1.0.0](../../insiders/changelog.md#1.0.0)
-
 Whether to render cross-references for type annotations in signatures.
 
 When signatures are separated from headings with the [`separate_signature`][] option

{mkdocstrings_python-1.18.2 → mkdocstrings_python-1.19.0}/docs/usage/index.md

@@ -380,3 +380,107 @@ poetry install
 poetry run mkdocs build
 ```
 ///
+
+## Recommended settings
+
+If you're in a hurry, here is the configuration we recommend for the Python handler.
+
+```yaml
+- mkdocstrings:
+    handlers:
+      python:
+
+        # Where to find your sources, see "Finding modules".
+        paths: [src]
+
+        # Load object inventories to enable cross-references to other projects.
+        inventories:
+        - https://docs.python.org/3/objects.inv
+        # Also load inventories of your dependencies, generally served at
+        # https://docs-url-for-your-dependency/objects.inv.
+
+        options:
+
+          # DOCSTRINGS -------------------------------------------------------------
+          docstring_options:
+            # Discard first line of `__init__` method docstrings,
+            # useful when merging such docstrings into their parent class'.
+            ignore_init_summary: true
+
+          # Tables are generally too large, lists will fix this.
+          docstring_section_style: list
+
+          # CROSS-REFERENCES -------------------------------------------------------
+          # Enable relative crossrefs and scoped crossrefs, see Docstrings options.
+          relative_crossrefs: true  # Sponsors only!
+          scoped_crossrefs: true  # Sponsors only!
+
+          # Enable cross-references in signatures.
+          signature_crossrefs: true
+
+          # Unwrap actual types from `Annotated` type annotations.
+          unwrap_annotated: true
+
+          # MEMBERS ----------------------------------------------------------------
+          # Only render pulic symbols.
+          filters: public  # Sponsors only!
+          # Comment the option otherwise to get the default filters.
+
+          # Show class inherited members.
+          inherited_members: true
+
+          # Render auto-generated summaries of attributes, functions, etc.
+          # at the start of each symbol's documentation.
+          summary: true
+
+          # HEADINGS ---------------------------------------------------------------
+          # For auto-generated pages, one module per page,
+          # make the module heading be the H1 heading of the page.
+          heading_level: 1
+
+          # Render headings for parameters, making them linkable.
+          parameter_headings: true
+
+          # Render headings for type parameters too.
+          type_parameter_headings: true
+
+          # Always show the heading for the symbol you render with `::: id`.
+          show_root_heading: true
+
+          # Only show the name of the symbols you inject render `::: id`.
+          show_root_full_path: false
+
+          # Show the type of symbol (class, function, etc.) in the heading.
+          show_symbol_type_heading: true
+
+          # Show the type of symbol (class, function, etc.) in the table of contents.
+          show_symbol_type_toc: true
+
+          # SIGNATURES -------------------------------------------------------------
+          # Format code to 80 + 10% margin (Black and Ruff defaults)
+          # in signatures and attribute value code blocks.
+          # Needs Black/Ruff installed.
+          line_length: 88
+
+          # Merge signature and docstring of `__init__` methods
+          # into their parent class signature and docstring.
+          merge_init_into_class: true
+
+          # Render signatures and attribute values in a separate code block,
+          # below the symbol heading.
+          separate_signature: true
+
+          # Show type annotations in signatures.
+          show_signature_annotations: true
+
+          # Show type parameters in signatures.
+          show_signature_type_parameters: true
+
+          # OTHER ------------------------------------------------------------------
+          # Show backlinks to other documentation sections within each symbol.
+          backlinks: tree  # Sponsors only!
+
+          # Show base classes OR inheritance diagram.
+          show_bases: false
+          show_inheritance_diagram: true  # Sponsors only!
+```