mkdocstrings-python 2.0.10__tar.gz → 2.0.11__tar.gz

{mkdocstrings_python-2.0.10 → mkdocstrings_python-2.0.11}/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).
 
 <!-- insertion marker -->
+## [2.0.11](https://github.com/mkdocstrings/python/releases/tag/2.0.11) - 2026-11-12
+
+<small>[Compare with 2.0.10](https://github.com/mkdocstrings/python/compare/2.0.10...2.0.11)</small>
+
+### Bug Fixes
+
+- Add missing closing parenthesis around type parameter type ([ecfd54d](https://github.com/mkdocstrings/python/commit/ecfd54d4a7530fbed1f53ac023c37ae7d247b9db) by Timothée Mazzucotelli). [Issue-349](https://github.com/mkdocstrings/python/issues/349)
+- Use Griffe's `reference_path` to avoid cross-referencing irrelevant headings ([1f0fa78](https://github.com/mkdocstrings/python/commit/1f0fa78282c03cbbf10d170cc6bd96979bc29c9e) by Timothée Mazzucotelli). [Issue-347](https://github.com/mkdocstrings/python/issues/347)
+
 ## [2.0.10](https://github.com/mkdocstrings/python/releases/tag/2.0.10) - 2026-10-19
 
 <small>[Compare with 2.0.9](https://github.com/mkdocstrings/python/compare/2.0.9...2.0.10)</small>

{mkdocstrings_python-2.0.10 → mkdocstrings_python-2.0.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mkdocstrings-python
-Version: 2.0.10
+Version: 2.0.11
 Summary: A Python handler for mkdocstrings.
 Author-Email: Timothée Mazzucotelli <dev@pawamoy.fr>
 License-Expression: ISC
@@ -30,7 +30,7 @@ Project-URL: Funding, https://github.com/sponsors/pawamoy
 Requires-Python: >=3.11
 Requires-Dist: mkdocstrings>=1.0.8
 Requires-Dist: mkdocs-autorefs>=1.4
-Requires-Dist: griffelib>=2.0
+Requires-Dist: griffelib>=2.4
 Requires-Dist: typing-extensions>=4.0; python_version < "3.11"
 Description-Content-Type: text/markdown
 
@@ -120,10 +120,6 @@ dependencies = [
 
 <div id="premium-sponsors" style="text-align: center;">
 
-<div id="silver-sponsors"><b>Silver sponsors</b><p>
-<a href="https://fastapi.tiangolo.com/"><img alt="FastAPI" src="https://raw.githubusercontent.com/tiangolo/fastapi/master/docs/en/docs/img/logo-margin/logo-teal.png" style="height: 200px; "></a><br>
-</p></div>
-
 <div id="bronze-sponsors"><b>Bronze sponsors</b><p>
 <a href="https://www.nixtla.io/"><picture><source media="(prefers-color-scheme: light)" srcset="https://www.nixtla.io/img/logo/full-black.svg"><source media="(prefers-color-scheme: dark)" srcset="https://www.nixtla.io/img/logo/full-white.svg"><img alt="Nixtla" src="https://www.nixtla.io/img/logo/full-black.svg" style="height: 60px; "></picture></a><br>
 </p></div>
@@ -137,6 +133,7 @@ dependencies = [
 <a href="https://github.com/tlambert03"><img alt="tlambert03" src="https://avatars.githubusercontent.com/u/1609449?u=922abf0524b47739b37095e553c99488814b05db&v=4" style="height: 32px; border-radius: 100%;"></a>
 <a href="https://github.com/ssbarnea"><img alt="ssbarnea" src="https://avatars.githubusercontent.com/u/102495?u=c7bd9ddf127785286fc939dd18cb02db0a453bce&v=4" style="height: 32px; border-radius: 100%;"></a>
 <a href="https://github.com/femtomc"><img alt="femtomc" src="https://avatars.githubusercontent.com/u/34410036?u=f13a71daf2a9f0d2da189beaa94250daa629e2d8&v=4" style="height: 32px; border-radius: 100%;"></a>
+<a href="https://fastapi.tiangolo.com/"><img alt="FastAPI" src="https://raw.githubusercontent.com/tiangolo/fastapi/master/docs/en/docs/img/logo-margin/logo-teal.png" style="height: 200px; "></a>
 <a href="https://github.com/cmarqu"><img alt="cmarqu" src="https://avatars.githubusercontent.com/u/360986?v=4" style="height: 32px; border-radius: 100%;"></a>
 <a href="https://github.com/kolenaIO"><img alt="kolenaIO" src="https://avatars.githubusercontent.com/u/77010818?v=4" style="height: 32px; border-radius: 100%;"></a>
 <a href="https://github.com/ramnes"><img alt="ramnes" src="https://avatars.githubusercontent.com/u/835072?u=3fca03c3ba0051e2eb652b1def2188a94d1e1dc2&v=4" style="height: 32px; border-radius: 100%;"></a>
@@ -155,7 +152,6 @@ dependencies = [
 <a href="https://github.com/15r10nk"><img alt="15r10nk" src="https://avatars.githubusercontent.com/u/44680962?u=f04826446ff165742efa81e314bd03bf1724d50e&v=4" style="height: 32px; border-radius: 100%;"></a>
 <a href="https://github.com/activeloopai"><img alt="activeloopai" src="https://avatars.githubusercontent.com/u/34816118?v=4" style="height: 32px; border-radius: 100%;"></a>
 <a href="https://github.com/roboflow"><img alt="roboflow" src="https://avatars.githubusercontent.com/u/53104118?v=4" style="height: 32px; border-radius: 100%;"></a>
-<a href="https://github.com/cmclaughlin"><img alt="cmclaughlin" src="https://avatars.githubusercontent.com/u/1061109?u=ddf6eec0edd2d11c980f8c3aa96e3d044d4e0468&v=4" style="height: 32px; border-radius: 100%;"></a>
 <a href="https://github.com/RapidataAI"><img alt="RapidataAI" src="https://avatars.githubusercontent.com/u/104209891?v=4" style="height: 32px; border-radius: 100%;"></a>
 <a href="https://github.com/rodolphebarbanneau"><img alt="rodolphebarbanneau" src="https://avatars.githubusercontent.com/u/46493454?u=6c405452a40c231cdf0b68e97544e07ee956a733&v=4" style="height: 32px; border-radius: 100%;"></a>
 <a href="https://github.com/theSymbolSyndicate"><img alt="theSymbolSyndicate" src="https://avatars.githubusercontent.com/u/111542255?v=4" style="height: 32px; border-radius: 100%;"></a>

{mkdocstrings_python-2.0.10 → mkdocstrings_python-2.0.11}/README.md

@@ -84,10 +84,6 @@ dependencies = [
 
 <div id="premium-sponsors" style="text-align: center;">
 
-<div id="silver-sponsors"><b>Silver sponsors</b><p>
-<a href="https://fastapi.tiangolo.com/"><img alt="FastAPI" src="https://raw.githubusercontent.com/tiangolo/fastapi/master/docs/en/docs/img/logo-margin/logo-teal.png" style="height: 200px; "></a><br>
-</p></div>
-
 <div id="bronze-sponsors"><b>Bronze sponsors</b><p>
 <a href="https://www.nixtla.io/"><picture><source media="(prefers-color-scheme: light)" srcset="https://www.nixtla.io/img/logo/full-black.svg"><source media="(prefers-color-scheme: dark)" srcset="https://www.nixtla.io/img/logo/full-white.svg"><img alt="Nixtla" src="https://www.nixtla.io/img/logo/full-black.svg" style="height: 60px; "></picture></a><br>
 </p></div>
@@ -101,6 +97,7 @@ dependencies = [
 <a href="https://github.com/tlambert03"><img alt="tlambert03" src="https://avatars.githubusercontent.com/u/1609449?u=922abf0524b47739b37095e553c99488814b05db&v=4" style="height: 32px; border-radius: 100%;"></a>
 <a href="https://github.com/ssbarnea"><img alt="ssbarnea" src="https://avatars.githubusercontent.com/u/102495?u=c7bd9ddf127785286fc939dd18cb02db0a453bce&v=4" style="height: 32px; border-radius: 100%;"></a>
 <a href="https://github.com/femtomc"><img alt="femtomc" src="https://avatars.githubusercontent.com/u/34410036?u=f13a71daf2a9f0d2da189beaa94250daa629e2d8&v=4" style="height: 32px; border-radius: 100%;"></a>
+<a href="https://fastapi.tiangolo.com/"><img alt="FastAPI" src="https://raw.githubusercontent.com/tiangolo/fastapi/master/docs/en/docs/img/logo-margin/logo-teal.png" style="height: 200px; "></a>
 <a href="https://github.com/cmarqu"><img alt="cmarqu" src="https://avatars.githubusercontent.com/u/360986?v=4" style="height: 32px; border-radius: 100%;"></a>
 <a href="https://github.com/kolenaIO"><img alt="kolenaIO" src="https://avatars.githubusercontent.com/u/77010818?v=4" style="height: 32px; border-radius: 100%;"></a>
 <a href="https://github.com/ramnes"><img alt="ramnes" src="https://avatars.githubusercontent.com/u/835072?u=3fca03c3ba0051e2eb652b1def2188a94d1e1dc2&v=4" style="height: 32px; border-radius: 100%;"></a>
@@ -119,7 +116,6 @@ dependencies = [
 <a href="https://github.com/15r10nk"><img alt="15r10nk" src="https://avatars.githubusercontent.com/u/44680962?u=f04826446ff165742efa81e314bd03bf1724d50e&v=4" style="height: 32px; border-radius: 100%;"></a>
 <a href="https://github.com/activeloopai"><img alt="activeloopai" src="https://avatars.githubusercontent.com/u/34816118?v=4" style="height: 32px; border-radius: 100%;"></a>
 <a href="https://github.com/roboflow"><img alt="roboflow" src="https://avatars.githubusercontent.com/u/53104118?v=4" style="height: 32px; border-radius: 100%;"></a>
-<a href="https://github.com/cmclaughlin"><img alt="cmclaughlin" src="https://avatars.githubusercontent.com/u/1061109?u=ddf6eec0edd2d11c980f8c3aa96e3d044d4e0468&v=4" style="height: 32px; border-radius: 100%;"></a>
 <a href="https://github.com/RapidataAI"><img alt="RapidataAI" src="https://avatars.githubusercontent.com/u/104209891?v=4" style="height: 32px; border-radius: 100%;"></a>
 <a href="https://github.com/rodolphebarbanneau"><img alt="rodolphebarbanneau" src="https://avatars.githubusercontent.com/u/46493454?u=6c405452a40c231cdf0b68e97544e07ee956a733&v=4" style="height: 32px; border-radius: 100%;"></a>
 <a href="https://github.com/theSymbolSyndicate"><img alt="theSymbolSyndicate" src="https://avatars.githubusercontent.com/u/111542255?v=4" style="height: 32px; border-radius: 100%;"></a>

{mkdocstrings_python-2.0.10 → mkdocstrings_python-2.0.11}/docs/usage/configuration/general.md

@@ -247,6 +247,8 @@ Whether to force inspecting modules (importing them) even if their source code i
 
 This option is useful when you know that dynamic analysis (inspection) yields better results than static analysis. Do not use this blindly: the recommended approach is to write a Griffe extension that will improve extracted API data. See [How to selectively inspect objects](https://mkdocstrings.github.io/griffe/guide/users/how-to/selectively-inspect/).
 
+To document lazy module members, set `force_inspection: true` and ensure the module exposes their names through `__dir__` and their values through `__getattr__`. See [Lazy module members](https://mkdocstrings.github.io/griffe/guide/users/loading/#lazy-module-members) for an example.
+
 See also [`allow_inspection`](#allow_inspection).
 
 ```yaml title="in mkdocs.yml (global configuration)"

{mkdocstrings_python-2.0.10 → mkdocstrings_python-2.0.11}/pyproject.toml

@@ -37,10 +37,10 @@ classifiers = [
 dependencies = [
     "mkdocstrings>=1.0.8",
     "mkdocs-autorefs>=1.4",
-    "griffelib>=2.0",
+    "griffelib>=2.4",
     "typing-extensions>=4.0; python_version < '3.11'",
 ]
-version = "2.0.10"
+version = "2.0.11"
 
 [project.urls]
 Homepage = "https://mkdocstrings.github.io/python"

{mkdocstrings_python-2.0.10 → mkdocstrings_python-2.0.11}/src/mkdocstrings_handlers/python/templates/material/_base/docstring/type_parameters.html.jinja

@@ -124,7 +124,7 @@ Context:
               <code>{% include "expression.html.jinja" with context %}</code>
             {%- endwith -%}
           {%- endif -%}
-          {%- if type_parameter.constraints or type_parameter.default -%}
+          {%- if type_parameter.bound or type_parameter.constraints or type_parameter.default -%}
             )
           {% endif -%}
           –

{mkdocstrings_python-2.0.10 → mkdocstrings_python-2.0.11}/src/mkdocstrings_handlers/python/templates/material/_base/expression.html.jinja

@@ -54,22 +54,27 @@ Context:
     {%- elif annotation_path == "full" -%}
       {%- set annotation = full -%}
     {%- endif -%}
-    {%- for prefix, title, path, suffix in annotation|split_path(full) -%}
-      {{ prefix }}
-      {%- if not signature -%}
-        {#- Always render cross-references outside of signatures. We don't need to stash them. -#}
-        <autoref identifier="{{ path }}"{% if backlink_type %} backlink-type="{{ backlink_type }}" backlink-anchor="{{ html_id }}"{% endif %} optional{% if title != path %} hover{% endif %}>{{ title }}</autoref>
-      {%- elif config.signature_crossrefs -%}
-        {#- We're in a signature and cross-references are enabled, we must render one and stash it. -#}
-        {%- filter stash_crossref(length=title|length) -%}
+    {%- if name.reference_path is none -%}
+      {#- Unresolved names can match unrelated headings, so render them as plain text. -#}
+      {{ annotation }}
+    {%- else -%}
+      {%- for prefix, title, path, suffix in annotation|split_path(name.reference_path) -%}
+        {{ prefix }}
+        {%- if not signature -%}
+          {#- Always render cross-references outside of signatures. We don't need to stash them. -#}
           <autoref identifier="{{ path }}"{% if backlink_type %} backlink-type="{{ backlink_type }}" backlink-anchor="{{ html_id }}"{% endif %} optional{% if title != path %} hover{% endif %}>{{ title }}</autoref>
-        {%- endfilter -%}
-      {%- else -%}
-        {#- We're in a signature but cross-references are disabled, we just render the title. -#}
-        {{ title }}
-      {%- endif -%}
-      {{ suffix }}
-    {%- endfor -%}
+        {%- elif config.signature_crossrefs -%}
+          {#- We're in a signature and cross-references are enabled, we must render one and stash it. -#}
+          {%- filter stash_crossref(length=title|length) -%}
+            <autoref identifier="{{ path }}"{% if backlink_type %} backlink-type="{{ backlink_type }}" backlink-anchor="{{ html_id }}"{% endif %} optional{% if title != path %} hover{% endif %}>{{ title }}</autoref>
+          {%- endfilter -%}
+        {%- else -%}
+          {#- We're in a signature but cross-references are disabled, we just render the title. -#}
+          {{ title }}
+        {%- endif -%}
+        {{ suffix }}
+      {%- endfor -%}
+    {%- endif -%}
   {%- endwith -%}
 {%- endmacro -%}
 
@@ -82,11 +87,13 @@ Context:
   Returns:
       The autorefs cross-reference, or the type parameter name.
   -#}
-  {%- if not signature -%}
-    <autoref identifier="{{ name.canonical_path }}" optional{% if name.name not in obj.type_parameters %} hover{% endif %}>{{ name.name }}</autoref>
+  {%- if name.reference_path is none -%}
+    {{ name.name }}
+  {%- elif not signature -%}
+    <autoref identifier="{{ name.reference_path }}" optional{% if name.name not in obj.type_parameters %} hover{% endif %}>{{ name.name }}</autoref>
   {%- elif config.signature_crossrefs -%}
     {%- filter stash_crossref(length=name.name|length) -%}
-      <autoref identifier="{{ name.canonical_path }}" optional{% if name.name not in obj.type_parameters %} hover{% endif %}>{{ name.name }}</autoref>
+      <autoref identifier="{{ name.reference_path }}" optional{% if name.name not in obj.type_parameters %} hover{% endif %}>{{ name.name }}</autoref>
     {%- endfilter -%}
   {%- else -%}
     {{ name.name }}
@@ -102,13 +109,13 @@ Context:
   Returns:
       The autorefs cross-reference, or the parameter name.
   -#}
-  {%- if config.signature_crossrefs -%}
+  {%- if config.signature_crossrefs and expression.reference_path is not none -%}
     {%- if signature -%}
       {%- filter stash_crossref(length=expression.name|length) -%}
-        <autoref identifier="{{ expression.canonical_path }}" optional hover>{{ expression.name }}</autoref>
+        <autoref identifier="{{ expression.reference_path }}" optional hover>{{ expression.name }}</autoref>
       {%- endfilter -%}
     {%- else -%}
-      <autoref identifier="{{ expression.canonical_path }}" optional hover>{{ expression.name }}</autoref>
+      <autoref identifier="{{ expression.reference_path }}" optional hover>{{ expression.name }}</autoref>
     {%- endif -%}
   {%- else -%}
     {{ expression.name }}

{mkdocstrings_python-2.0.10 → mkdocstrings_python-2.0.11}/tests/test_handler.py

@@ -206,6 +206,79 @@ def test_rendering_object_source_without_lineno(handler: PythonHandler) -> None:
         assert handler.render(module, PythonOptions(show_source=True))
 
 
+@pytest.mark.parametrize("annotations_path", ["brief", "source", "full"])
+@pytest.mark.parametrize(
+    ("code", "expected_text", "expected_targets"),
+    [
+        ("value = intro", "intro", []),
+        ("value = intro.attr", "intro.attr", []),
+        ("value = intro(keyword=1)", "intro(keyword=1)", []),
+        ("value = int", "int", ["int"]),
+        ("from pathlib import Path\nvalue = Path", None, ["pathlib.Path"]),
+        ("def factory(keyword): ...\nvalue = factory(keyword=1)", None, ["module.factory", "module.factory(keyword)"]),
+    ],
+)
+def test_expression_crossrefs(
+    handler: PythonHandler,
+    annotations_path: str,
+    code: str,
+    expected_text: str | None,
+    expected_targets: list[str],
+) -> None:
+    """Cross-reference resolved names and builtins while leaving unknown names as text."""
+    with temporary_visited_module(code) as module:
+        template = handler.env.get_template("expression.html.jinja")
+
+        html = template.render(
+            expression=module["value"].value,
+            config=handler.get_options({"annotations_path": annotations_path, "signature_crossrefs": True}),
+        )
+
+    soup = bs4.BeautifulSoup(html, "html.parser")
+    targets = [ref["identifier"] for ref in soup.find_all("autoref")]
+
+    # Full paths can also link their prefixes, but unknown names must have no targets.
+    assert all(target in targets for target in expected_targets)
+    if not expected_targets:
+        assert not targets
+    if expected_text is not None:
+        if annotations_path == "brief":
+            expected_text = expected_text.rsplit(".", 1)[-1]
+        assert soup.get_text() == expected_text
+
+
+@pytest.mark.parametrize("signature_crossrefs", [True, False])
+def test_instance_attribute_local_value_crossref(handler: PythonHandler, signature_crossrefs: bool) -> None:
+    """Keep a local variable's name visible without linking it to an unrelated heading."""
+    code = """
+        class Class:
+            def __init__(self):
+                intro = "Some text"
+                self.attr: str = intro
+    """
+    with temporary_visited_module(code) as module:
+        options = handler.get_options(
+            {
+                "separate_signature": True,
+                "signature_crossrefs": signature_crossrefs,
+                "show_signature_annotations": True,
+                "show_root_heading": True,
+                "show_source": False,
+            },
+        )
+
+        html = handler.render(module["Class.attr"], options)
+
+    soup = bs4.BeautifulSoup(html, "html.parser")
+    signature = soup.select_one(".doc-signature")
+    assert signature is not None
+    assert signature.get_text(strip=True) == "attr:str=intro"
+
+    # The builtin annotation can link; the unresolved local value cannot.
+    targets = [ref["identifier"] for ref in signature.find_all("autoref")]
+    assert targets == (["str"] if signature_crossrefs else [])
+
+
 @pytest.mark.parametrize(
     ("handler", "merge_init_into_class"),
     [