diff --git a/CHANGELOG.md b/CHANGELOG.md index 3769a7eb..0ea1cfbd 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,15 @@ 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). +## [2.0.5](https://github.com/mkdocstrings/python/releases/tag/2.0.5) - 2026-06-19 + +[Compare with 2.0.4](https://github.com/mkdocstrings/python/compare/2.0.4...2.0.5) + +### Bug Fixes + +- Allow relative cross-references to work in summaries ([abe2888](https://github.com/mkdocstrings/python/commit/abe28889584df8fb0bc923dfad6f2ddaff41bb7a) by Timothée Mazzucotelli). [Issue-331](https://github.com/mkdocstrings/python/issues/331) +- Always display attribute values as they're written in the source ([0334131](https://github.com/mkdocstrings/python/commit/033413123b95c0788f500b871f00ed1223ae2b82) by Timothée Mazzucotelli). [Issue-311](https://github.com/mkdocstrings/python/issues/311) + ## [2.0.4](https://github.com/mkdocstrings/python/releases/tag/2.0.4) - 2026-06-05 [Compare with 2.0.3](https://github.com/mkdocstrings/python/compare/2.0.3...2.0.4) diff --git a/docs/usage/configuration/docstrings.md b/docs/usage/configuration/docstrings.md index 95f9032f..dc2d6c2c 100644 --- a/docs/usage/configuration/docstrings.md +++ b/docs/usage/configuration/docstrings.md @@ -214,8 +214,8 @@ In that case, the Spacy tables can help. **Type** | **Name** | **Description** | **Default** ---------- | ----------- | ------------------------ | ----------- -list[int \| float] | `gravity_forces` | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. | *required* -VacuumType \| Literal["regular"] | `vacuum_type` | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. | `VacuumType.PLASMA` +list\[int \| float\] | `gravity_forces` | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. | *required* +VacuumType \| Literal\["regular"\] | `vacuum_type` | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. | `VacuumType.PLASMA` //// //// tab | List @@ -228,8 +228,8 @@ Lists work well whatever the length of names, type annotations, descriptions, et **Other Parameters:** -- `gravity_forces` (list[int \| float]) — Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. -- `vacuum_type` (VacuumType \| Literal["regular"]) — Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. +- `gravity_forces` (list\[int \| float\]) — Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. +- `vacuum_type` (VacuumType \| Literal\["regular"\]) — Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. //// //// tab | Spacy @@ -247,8 +247,8 @@ by reserving more horizontal space on the second column. **Name** | **Description** ----------- | --------------- -`gravity_forces` | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
**TYPE:** list[int \| float] DEFAULT: required -`vacuum_type` | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
**TYPE:**VacuumType \| Literal["regular"] DEFAULT: VacuumType.PLASMA +`gravity_forces` | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
**TYPE:** list\[int \| float\] DEFAULT: required +`vacuum_type` | Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
**TYPE:**VacuumType \| Literal\["regular"\] DEFAULT: VacuumType.PLASMA //// /// diff --git a/docs/usage/configuration/general.md b/docs/usage/configuration/general.md index 921f3b27..f44f4ac1 100644 --- a/docs/usage/configuration/general.md +++ b/docs/usage/configuration/general.md @@ -63,7 +63,7 @@ plugins: [](){#option-backlinks} ## `backlinks` -- **:octicons-package-24: Type Literal["flat", "tree", False] :material-equal: `False`{ title="default value" }** +- **:octicons-package-24: Type Literal\["flat", "tree", False\] :material-equal: `False`{ title="default value" }** The `backlinks` option enables rendering of backlinks within your API documentation. @@ -102,7 +102,7 @@ plugins: [](){#option-extensions} ## `extensions` -- **:octicons-package-24: Type list[str | dict[str, dict[str, Any]]] :material-equal: `[]`{ title="default value" }** +- **:octicons-package-24: Type list\[str | dict\[str, dict\[str, Any\]\]\] :material-equal: `[]`{ title="default value" }** The `extensions` option lets you enable [Griffe extensions](https://mkdocstrings.github.io/griffe/extensions/), which enhance or modify the data collected from Python sources (or compiled modules). @@ -406,7 +406,7 @@ Mixin2A --> Mixin2B [](){#option-preload_modules} ## `preload_modules` -- **:octicons-package-24: Type list[str] | None :material-equal: `None`{ title="default value" }** +- **:octicons-package-24: Type list\[str\] | None :material-equal: `None`{ title="default value" }** Pre-load modules that are not specified directly in [autodoc instructions][autodoc syntax] (`::: identifier`). diff --git a/docs/usage/configuration/headings.md b/docs/usage/configuration/headings.md index 593b6fb0..5d261807 100644 --- a/docs/usage/configuration/headings.md +++ b/docs/usage/configuration/headings.md @@ -191,7 +191,7 @@ plugins: get_version
dist -To customize symbols, see [Customizing symbol types](../customization.md/#symbol-types). +To customize symbols, see [Customizing symbol types](../customization.md#symbol-types). /// @@ -303,6 +303,10 @@ More text. /// admonition | Preview type: preview +[](){#permalink-to-some-heading} +[](){#permalink-to-object} +[](){#permalink-to-other-heading} + //// tab | With ToC entry **Table of contents** [Some heading](#permalink-to-some-heading){ title="#permalink-to-some-heading" } @@ -548,7 +552,7 @@ This option will prefix headings with types. See also [`show_symbol_type_toc`][show_symbol_type_toc]. -To customize symbols, see [Customizing symbol types](../customization.md/#symbol-types). +To customize symbols, see [Customizing symbol types](../customization.md#symbol-types). ```yaml title="in mkdocs.yml (global configuration)" plugins: @@ -611,7 +615,7 @@ This option will prefix items in the ToC with types. See also [`show_symbol_type_heading`][show_symbol_type_heading]. -To customize symbols, see [Customizing symbol types](../customization.md/#symbol-types). +To customize symbols, see [Customizing symbol types](../customization.md#symbol-types). ```yaml title="in mkdocs.yml (global configuration)" plugins: diff --git a/docs/usage/configuration/members.md b/docs/usage/configuration/members.md index 53d955fa..b6a65c30 100644 --- a/docs/usage/configuration/members.md +++ b/docs/usage/configuration/members.md @@ -3,7 +3,7 @@ [](){#option-members} ## `members` -- **:octicons-package-24: Type list[str] | +- **:octicons-package-24: Type list\[str\] | bool | None :material-equal: `None`{ title="default value" }** @@ -99,7 +99,7 @@ INFO: **The default behavior (with unspecified `members` or `members: null`) is [](){#option-inherited_members} ## `inherited_members` -- **:octicons-package-24: Type list[str] | +- **:octicons-package-24: Type list\[str\] | bool :material-equal: `False`{ title="default value" }** @@ -342,7 +342,7 @@ def function_c(): [](){#option-filters} ## `filters` -- **:octicons-package-24: Type list[str] | Literal["public"] | None :material-equal: `["!^_[^_]"]`{ title="default value" }** +- **:octicons-package-24: Type list\[str\] | Literal\["public"\] | None :material-equal: `["!^_[^_]"]`{ title="default value" }** A list of filters, or `"public"`. @@ -574,7 +574,7 @@ package [](){#option-summary} ## `summary` -- **:octicons-package-24: Type bool | dict[str, bool] :material-equal: `False`{ title="default value" }** +- **:octicons-package-24: Type bool | dict\[str, bool\] :material-equal: `False`{ title="default value" }** Whether to render summaries of modules, classes, functions (methods) and attributes. diff --git a/docs/usage/configuration/signatures.md b/docs/usage/configuration/signatures.md index 109362e3..c9ac917b 100644 --- a/docs/usage/configuration/signatures.md +++ b/docs/usage/configuration/signatures.md @@ -64,6 +64,8 @@ def convert(text: str, md: markdown.Markdown) -> markupsafe.Markup:

Convert text to Markdown.

Parameters:

+[](){#ref-to-markdown} + **Type** | **Description** | **Default** ---------- | ------------------------ | ----------- [`str`][] | The text to convert. | *required* @@ -71,6 +73,8 @@ def convert(text: str, md: markdown.Markdown) -> markupsafe.Markup:

Returns:

+[](){#ref-to-markup} + **Type** | **Name** | **Description** ---------- | ----------- | --------------- [`Markup`](#ref-to-markup){ .external title="markupsafe.Markup" } | `text` | Converted markup. diff --git a/duties.py b/duties.py index 3aa9b662..8bf362fc 100644 --- a/duties.py +++ b/duties.py @@ -78,7 +78,7 @@ def check_docs(ctx: Context) -> None: ) -@duty(nofail=PY_VERSION == PY_DEV) +@duty(nofail=True) def check_types(ctx: Context) -> None: """Check that the code is correctly typed.""" os.environ["MYPYPATH"] = "src" @@ -86,8 +86,6 @@ def check_types(ctx: Context) -> None: ctx.run( tools.mypy(*PY_SRC_LIST, config_file="config/mypy.ini"), title=pyprefix("Type-checking"), - # TODO: Update when Pydantic supports 3.14. - nofail=sys.version_info >= (3, 14), ) diff --git a/src/mkdocstrings_handlers/python/_internal/rendering.py b/src/mkdocstrings_handlers/python/_internal/rendering.py index a906b465..d5ffc8e9 100644 --- a/src/mkdocstrings_handlers/python/_internal/rendering.py +++ b/src/mkdocstrings_handlers/python/_internal/rendering.py @@ -245,7 +245,13 @@ def do_format_attribute( ) signature += f": {annotation}" if show_value and attribute.value: - value = template.render(context.parent, expression=attribute.value, signature=True, backlink_type="used-by") + value = template.render( + context.parent, + expression=attribute.value, + signature=True, + annotations_path="source", + backlink_type="used-by", + ) signature += f" = {value}" signature = do_format_code(signature, line_length) diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html.jinja index 894639a7..e336e46e 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/attributes.html.jinja @@ -43,7 +43,7 @@ Context:
- {{ attribute.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} + {{ attribute.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook|default(AutorefsHook(obj[attribute.name], config))) }}
@@ -66,7 +66,7 @@ Context: {% endif %} –
- {{ attribute.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} + {{ attribute.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook|default(AutorefsHook(obj[attribute.name], config))) }}
{% endfor %} @@ -88,7 +88,7 @@ Context: {{ attribute.name }}
- {{ attribute.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} + {{ attribute.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook|default(AutorefsHook(obj[attribute.name], config))) }}

{% if attribute.annotation %} @@ -106,4 +106,4 @@ Context: {% endblock spacy_style %} -{% endif %} \ No newline at end of file +{% endif %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/classes.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/classes.html.jinja index b139a761..7dff6c9c 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/classes.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/classes.html.jinja @@ -35,7 +35,7 @@ Context: {{ class.name }}

- {{ class.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} + {{ class.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook|default(AutorefsHook(obj[class.name], config))) }}
@@ -53,7 +53,7 @@ Context: {{ class.name }} –
- {{ class.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} + {{ class.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook|default(AutorefsHook(obj[class.name], config))) }}
{% endfor %} @@ -75,7 +75,7 @@ Context: {{ class.name }}
- {{ class.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} + {{ class.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook|default(AutorefsHook(obj[class.name], config))) }}
@@ -83,4 +83,4 @@ Context: {% endblock spacy_style %} -{% endif %} \ No newline at end of file +{% endif %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/functions.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/functions.html.jinja index afec8f60..ad9e3b25 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/functions.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/functions.html.jinja @@ -36,7 +36,7 @@ Context: {{ function.name }}
- {{ function.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} + {{ function.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook|default(AutorefsHook(obj[function.name], config))) }}
@@ -56,7 +56,7 @@ Context: {{ function.name }} –
- {{ function.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} + {{ function.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook|default(AutorefsHook(obj[function.name], config))) }}
{% endif %} @@ -80,7 +80,7 @@ Context: {{ function.name }}
- {{ function.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} + {{ function.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook|default(AutorefsHook(obj[function.name], config))) }}
@@ -89,4 +89,4 @@ Context: {% endblock spacy_style %} -{% endif %} \ No newline at end of file +{% endif %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/modules.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/modules.html.jinja index 5556cf15..d366d0db 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/modules.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/modules.html.jinja @@ -35,7 +35,7 @@ Context: {{ module.name }}
- {{ module.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} + {{ module.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook|default(AutorefsHook(obj[module.name], config))) }}
@@ -53,7 +53,7 @@ Context: {{ module.name }} –
- {{ module.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} + {{ module.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook|default(AutorefsHook(obj[module.name], config))) }}
{% endfor %} @@ -75,7 +75,7 @@ Context: {{ module.name }}
- {{ module.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} + {{ module.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook|default(AutorefsHook(obj[module.name], config))) }}
@@ -83,4 +83,4 @@ Context: {% endblock spacy_style %} -{% endif %} \ No newline at end of file +{% endif %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/type_aliases.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/type_aliases.html.jinja index e1c87754..3ccd947c 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/docstring/type_aliases.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/docstring/type_aliases.html.jinja @@ -35,7 +35,7 @@ Context: {{ type_alias.name }}
- {{ type_alias.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} + {{ type_alias.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook|default(AutorefsHook(obj[type_alias.name], config))) }}
@@ -53,7 +53,7 @@ Context: {{ type_alias.name }} –
- {{ type_alias.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} + {{ type_alias.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook|default(AutorefsHook(obj[type_alias.name], config))) }}
{% endfor %} @@ -75,7 +75,7 @@ Context: {{ type_alias.name }}
- {{ type_alias.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook) }} + {{ type_alias.description|convert_markdown(heading_level, html_id, autoref_hook=autoref_hook|default(AutorefsHook(obj[type_alias.name], config))) }}
diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/expression.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/expression.html.jinja index 4f44ae00..60585a5a 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/expression.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/expression.html.jinja @@ -169,4 +169,4 @@ Context: {%- if config.modernize_annotations and expression is not string -%} {%- set expression = expression.modernize() -%} {%- endif -%} -{{ render(expression, config.annotations_path, backlink_type|default("")) }} +{{ render(expression, annotations_path|default(config.annotations_path), backlink_type|default("")) }}