From bb36fa1fdc9d0fba1211fbfea2d50768b126a282 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Tue, 20 May 2025 13:02:38 +0200 Subject: [PATCH 01/13] chore: Template upgrade --- .copier-answers.yml | 2 +- docs/css/material.css | 2 +- mkdocs.yml | 9 +++++---- pyproject.toml | 6 +++--- tests/test_api.py | 2 +- 5 files changed, 11 insertions(+), 10 deletions(-) diff --git a/.copier-answers.yml b/.copier-answers.yml index b2cee68e..76531124 100644 --- a/.copier-answers.yml +++ b/.copier-answers.yml @@ -1,5 +1,5 @@ # Changes here will be overwritten by Copier. -_commit: 1.4.0 +_commit: 1.4.5 _src_path: gh:mkdocstrings/handler-template author_email: dev@pawamoy.fr author_fullname: Timothée Mazzucotelli diff --git a/docs/css/material.css b/docs/css/material.css index 19c6b076..235ef946 100644 --- a/docs/css/material.css +++ b/docs/css/material.css @@ -23,4 +23,4 @@ background-color: rgb(220, 139, 240); -webkit-mask-image: var(--md-admonition-icon--preview); mask-image: var(--md-admonition-icon--preview); -} \ No newline at end of file +} diff --git a/mkdocs.yml b/mkdocs.yml index 6fc301b0..0199ea9a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -182,11 +182,12 @@ plugins: summary: true unwrap_annotated: true - llmstxt: - files: - - output: llms-full.txt - inputs: + full_output: llms-full.txt + sections: + Usage: - index.md - - reference/**.md + API: + - reference/api.md - git-revision-date-localized: enabled: !ENV [DEPLOY, false] enable_creation_date: true diff --git a/pyproject.toml b/pyproject.toml index 54f27585..d93cb20c 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -57,7 +57,7 @@ includes = ["src/mkdocstrings_handlers"] editable-backend = "editables" # Include as much as possible in the source distribution, to help redistributors. -excludes = ["**/.pytest_cache"] +excludes = ["**/.pytest_cache", "**/.mypy_cache"] source-includes = [ "config", "docs", @@ -105,13 +105,13 @@ ci = [ "mkdocs>=1.6", "mkdocs-coverage>=1.0", "mkdocs-git-revision-date-localized-plugin>=1.2", - "mkdocs-llmstxt>=0.1", + "mkdocs-llmstxt>=0.2", "mkdocs-material>=9.5", - "pydantic>=2.10", "mkdocs-minify-plugin>=0.8", "mkdocs-redirects>=1.2", "mkdocs-section-index>=0.3", "mkdocstrings>=0.29", + "pydantic>=2.10", # YORE: EOL 3.10: Remove line. "tomli>=2.0; python_version < '3.11'", ] diff --git a/tests/test_api.py b/tests/test_api.py index 490bd82d..6d0b8738 100644 --- a/tests/test_api.py +++ b/tests/test_api.py @@ -145,7 +145,7 @@ def test_api_matches_inventory(inventory: Inventory, public_objects: list[griffe def _module_or_child(parent: str, name: str) -> bool: - parents = [parent[: i + 1] for i, char in enumerate(parent) if char == "."] + parents = [parent[:i] for i, char in enumerate(parent) if char == "."] parents.append(parent) return name in parents or name.startswith(parent + ".") From d4e618ab794747b84dced848b1be824639fea2b8 Mon Sep 17 00:00:00 2001 From: David Lee Date: Tue, 20 May 2025 04:11:46 -0700 Subject: [PATCH 02/13] fix: Render attribute names without full path in ToC Issue-271: https://github.com/mkdocstrings/python/issues/271 PR-272: https://github.com/mkdocstrings/python/pull/272 --- .../python/templates/material/_base/attribute.html.jinja | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja index 7894c544..dd258191 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja @@ -39,7 +39,7 @@ Context: role="data" if attribute.parent.kind.value == "module" else "attr", id=html_id, class="doc doc-heading", - toc_label=(' '|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else attribute_name), + toc_label=(' '|safe if config.show_symbol_type_toc else '') + (config.toc_label if config.toc_label and root else attribute.name), ) %} {% block heading scoped %} From 096960abd79831d6fd45e2a7962dfd2bd49e4edd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Tue, 20 May 2025 14:37:42 +0200 Subject: [PATCH 03/13] fix: Use configured heading even when signature is not separated Issue-mkdocstrings-767: https://github.com/mkdocstrings/mkdocstrings/issues/767 PR-278: https://github.com/mkdocstrings/python/pull/278 --- .../material/_base/attribute.html.jinja | 6 ++- .../templates/material/_base/class.html.jinja | 6 ++- .../material/_base/function.html.jinja | 6 ++- .../material/_base/module.html.jinja | 6 ++- tests/snapshots/__init__.py | 18 +++++++ ...b25994087bc836868f63da18557a6094a00ee.html | 20 ++++++++ ...45132d578af0e1df1219c08bc9ea0bea1f39c.html | 18 +++++++ ...6d547a80dfbb41a311dabd94b96fd968b83bc.html | 18 +++++++ ...2a8236f43cade477f95e4ce4c9a60248f0a10.html | 20 ++++++++ tests/test_end_to_end.py | 51 ++++++++++++++++++- 10 files changed, 159 insertions(+), 10 deletions(-) create mode 100644 tests/snapshots/external/2eef87791b974c724d2cd98e40bb25994087bc836868f63da18557a6094a00ee.html create mode 100644 tests/snapshots/external/480324b25439ea41507fdda100045132d578af0e1df1219c08bc9ea0bea1f39c.html create mode 100644 tests/snapshots/external/51deee0f00f35b0902f82fb96a36d547a80dfbb41a311dabd94b96fd968b83bc.html create mode 100644 tests/snapshots/external/d1dd339f926026210ea46cc75922a8236f43cade477f95e4ce4c9a60248f0a10.html diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja index dd258191..519590e5 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja @@ -48,8 +48,10 @@ Context: This block renders the heading for the attribute. -#} {% if config.show_symbol_type_heading %}{% endif %} - {% if config.separate_signature %} - {{ config.heading if config.heading and root else attribute_name }} + {% if config.heading and root %} + {{ config.heading }} + {% elif config.separate_signature %} + {{ attribute_name }} {% else %} {%+ filter highlight(language="python", inline=True) %} {{ attribute_name }}{% if attribute.annotation and config.show_signature_annotations %}: {{ attribute.annotation }}{% endif %} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja index ae2f8de5..8a54dd1b 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/class.html.jinja @@ -47,8 +47,10 @@ Context: This block renders the heading for the class. -#} {% if config.show_symbol_type_heading %}{% endif %} - {% if config.separate_signature %} - {{ config.heading if config.heading and root else class_name }} + {% if config.heading and root %} + {{ config.heading }} + {% elif config.separate_signature %} + {{ class_name }} {% elif config.merge_init_into_class and "__init__" in all_members %} {% with function = all_members["__init__"] %} {%+ filter highlight(language="python", inline=True) -%} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja index e56bc7e4..21888939 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja @@ -54,8 +54,10 @@ Context: This block renders the heading for the function. -#} {% if config.show_symbol_type_heading %}{% endif %} - {% if config.separate_signature %} - {{ config.heading if config.heading and root else function_name }} + {% if config.heading and root %} + {{ config.heading }} + {% elif config.separate_signature %} + {{ function_name }} {% else %} {%+ filter highlight(language="python", inline=True) -%} {#- YORE: Bump 2: Replace `"|get_template` with `.html.jinja"` within line. -#} diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/module.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/module.html.jinja index d2b5516d..283f2654 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/module.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/module.html.jinja @@ -47,8 +47,10 @@ Context: This block renders the heading for the module. -#} {% if config.show_symbol_type_heading %}{% endif %} - {% if config.separate_signature %} - {{ config.heading if config.heading and root else module_name }} + {% if config.heading and root %} + {{ config.heading }} + {% elif config.separate_signature %} + {{ module_name }} {% else %} {{ module_name }} {% endif %} diff --git a/tests/snapshots/__init__.py b/tests/snapshots/__init__.py index e411bfa8..556133ac 100644 --- a/tests/snapshots/__init__.py +++ b/tests/snapshots/__init__.py @@ -383,5 +383,23 @@ (("filters", "public"), ("inherited_members", False), ("members", ("module_attribute",))): external( "80399c502938*.html", ), + (("heading", ""), ("members", False), ("separate_signature", False), ("show_if_no_docstring", True)): external( + "d1dd339f9260*.html", + ), + ( + ("heading", "Some heading"), + ("members", False), + ("separate_signature", True), + ("show_if_no_docstring", True), + ): external("480324b25439*.html"), + (("heading", ""), ("members", False), ("separate_signature", True), ("show_if_no_docstring", True)): external( + "2eef87791b97*.html", + ), + ( + ("heading", "Some heading"), + ("members", False), + ("separate_signature", False), + ("show_if_no_docstring", True), + ): external("51deee0f00f3*.html"), }, ) diff --git a/tests/snapshots/external/2eef87791b974c724d2cd98e40bb25994087bc836868f63da18557a6094a00ee.html b/tests/snapshots/external/2eef87791b974c724d2cd98e40bb25994087bc836868f63da18557a6094a00ee.html new file mode 100644 index 00000000..f0242792 --- /dev/null +++ b/tests/snapshots/external/2eef87791b974c724d2cd98e40bb25994087bc836868f63da18557a6094a00ee.html @@ -0,0 +1,20 @@ + + +
+

+ + headings_package + +

+
+
+
+
+
diff --git a/tests/snapshots/external/480324b25439ea41507fdda100045132d578af0e1df1219c08bc9ea0bea1f39c.html b/tests/snapshots/external/480324b25439ea41507fdda100045132d578af0e1df1219c08bc9ea0bea1f39c.html new file mode 100644 index 00000000..fd1f953b --- /dev/null +++ b/tests/snapshots/external/480324b25439ea41507fdda100045132d578af0e1df1219c08bc9ea0bea1f39c.html @@ -0,0 +1,18 @@ + + +
+

+ Some heading +

+
+
+
+
+
diff --git a/tests/snapshots/external/51deee0f00f35b0902f82fb96a36d547a80dfbb41a311dabd94b96fd968b83bc.html b/tests/snapshots/external/51deee0f00f35b0902f82fb96a36d547a80dfbb41a311dabd94b96fd968b83bc.html new file mode 100644 index 00000000..8601ee01 --- /dev/null +++ b/tests/snapshots/external/51deee0f00f35b0902f82fb96a36d547a80dfbb41a311dabd94b96fd968b83bc.html @@ -0,0 +1,18 @@ + + +
+

+ Some heading +

+
+
+
+
+
diff --git a/tests/snapshots/external/d1dd339f926026210ea46cc75922a8236f43cade477f95e4ce4c9a60248f0a10.html b/tests/snapshots/external/d1dd339f926026210ea46cc75922a8236f43cade477f95e4ce4c9a60248f0a10.html new file mode 100644 index 00000000..a9dd1e61 --- /dev/null +++ b/tests/snapshots/external/d1dd339f926026210ea46cc75922a8236f43cade477f95e4ce4c9a60248f0a10.html @@ -0,0 +1,20 @@ + + +
+

+ + headings_package + +

+
+
+
+
+
diff --git a/tests/test_end_to_end.py b/tests/test_end_to_end.py index 7a26cb53..3a96f803 100644 --- a/tests/test_end_to_end.py +++ b/tests/test_end_to_end.py @@ -59,7 +59,7 @@ def _render_options(options: dict[str, Any]) -> str: return f"\n\n" -# Signature options +# Signature tests. @pytest.fixture(name="signature_package", scope="session") def _signature_package() -> Iterator[TmpPackage]: code = """ @@ -108,7 +108,7 @@ def test_end_to_end_for_signatures( assert outsource(html, suffix=".html") == snapshots_signatures[snapshot_key] -# Members options. +# Member tests. @pytest.fixture(name="members_package", scope="session") def _members_package() -> Iterator[TmpPackage]: code = """ @@ -171,3 +171,50 @@ def test_end_to_end_for_members( html = _render_options(final_options) + _render(session_handler, members_package, final_options) snapshot_key = tuple(sorted(final_options.items())) assert outsource(html, suffix=".html") == snapshots_members[snapshot_key] + + +# Heading tests. +@pytest.fixture(name="headings_package", scope="session") +def _headings_package() -> Iterator[TmpPackage]: + code = """ + def module_function(a: int, b: str) -> None: + pass + + class Class: + class_attribute: int = 42 + + def __init__(self, a: int, b: str) -> None: + self.instance_attribute = a + b + + def method1(self, a: int, b: str) -> None: + pass + + module_attribute: int = 42 + """ + with temporary_pypackage("headings_package", {"__init__.py": code}) as tmppkg: + yield tmppkg + + +@pytest.mark.parametrize("separate_signature", [True, False]) +@pytest.mark.parametrize("heading", ["", "Some heading"]) +def test_end_to_end_for_headings( + session_handler: PythonHandler, + headings_package: TmpPackage, + separate_signature: bool, + heading: str, +) -> None: + """Test rendering of a given theme's templates. + + Parameters: + identifier: Parametrized identifier. + session_handler: Python handler (fixture). + """ + final_options = { + "separate_signature": separate_signature, + "heading": heading, + "show_if_no_docstring": True, + "members": False, + } + html = _render_options(final_options) + _render(session_handler, headings_package, final_options) + snapshot_key = tuple(sorted(final_options.items())) + assert outsource(html, suffix=".html") == snapshots_members[snapshot_key] From ba669697daad5067ea5db3fdf8a2d5ba2f966b25 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Tue, 20 May 2025 14:50:03 +0200 Subject: [PATCH 04/13] fix: Prevent uppercasing H5 titles (by Material for MkDocs) Issue-mkdocstrings-697: https://github.com/mkdocstrings/mkdocstrings/issues/697 Issue-276: https://github.com/mkdocstrings/python/issues/276 --- .../python/templates/material/style.css | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/mkdocstrings_handlers/python/templates/material/style.css b/src/mkdocstrings_handlers/python/templates/material/style.css index e5e150ec..33f63042 100644 --- a/src/mkdocstrings_handlers/python/templates/material/style.css +++ b/src/mkdocstrings_handlers/python/templates/material/style.css @@ -9,6 +9,11 @@ display: inline; } +/* No text transformation from Material for MkDocs for H5 headings. */ +.md-typeset h5 .doc-object-name { + text-transform: none; +} + /* Max width for docstring sections tables. */ .doc .md-typeset__table, .doc .md-typeset__table table { From 0a35b20a6050a28ba8492d93e5f9940a69462ce3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Tue, 20 May 2025 14:50:31 +0200 Subject: [PATCH 05/13] fix: Use default font-size for parameter headings Issue-mkdocstrings-697: https://github.com/mkdocstrings/mkdocstrings/issues/697 --- .../python/templates/material/style.css | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/src/mkdocstrings_handlers/python/templates/material/style.css b/src/mkdocstrings_handlers/python/templates/material/style.css index 33f63042..b8c3e639 100644 --- a/src/mkdocstrings_handlers/python/templates/material/style.css +++ b/src/mkdocstrings_handlers/python/templates/material/style.css @@ -35,6 +35,11 @@ display: inline; } +/* Default font size for parameter headings. */ +.md-typeset .doc-heading-parameter { + font-size: inherit; +} + /* Prefer space on the right, not the left of parameter permalinks. */ .doc-heading-parameter .headerlink { margin-left: 0 !important; From 7f956868f93a766346455fedb296c26787894d5c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Fri, 23 May 2025 15:10:20 +0200 Subject: [PATCH 06/13] fix: Fix highlighting for signature with known special names like `__init__` Issue-mkdocstrings-757: https://github.com/mkdocstrings/mkdocstrings/issues/757 --- .../python/_internal/rendering.py | 10 ++++++---- tests/snapshots/__init__.py | 8 ++++---- ...1265509d7c5b499fe3776aeeeb298db7589bb385ca019.html} | 2 +- ...3050af088e7341495708d879ab45ee9e8ab1dcac26f2a.html} | 2 +- ...8d4e5bf36b007810eb3730a7283624a4d68c6fe2ce652.html} | 2 +- ...2264400a83a1e693c146feec7c359855c676c4a586392.html} | 2 +- 6 files changed, 14 insertions(+), 12 deletions(-) rename tests/snapshots/external/{9c0bfc0ee40732505dc3dab8c95ad4ed6582d10df2449c7d92f1e43a91610666.html => 4041a38e355f6585a7e1265509d7c5b499fe3776aeeeb298db7589bb385ca019.html} (93%) rename tests/snapshots/external/{f5ce06acbb7a31658cc6367db31caaf7a210c0a31e71de950e791c5eb33a6258.html => 74ee37cd1e94250baa33050af088e7341495708d879ab45ee9e8ab1dcac26f2a.html} (89%) rename tests/snapshots/external/{4370d843cc76138927502402ac39c80414c8441a962f6466afdb280dc022af26.html => d03d16d1919af01db9b8d4e5bf36b007810eb3730a7283624a4d68c6fe2ce652.html} (93%) rename tests/snapshots/external/{261a38d7a86b5e959b6d1c165108301963d0170c2189d5aa18bb7c7eade84ea4.html => e412376be64f25f3f5d2264400a83a1e693c146feec7c359855c676c4a586392.html} (85%) diff --git a/src/mkdocstrings_handlers/python/_internal/rendering.py b/src/mkdocstrings_handlers/python/_internal/rendering.py index 8f544014..902d794e 100644 --- a/src/mkdocstrings_handlers/python/_internal/rendering.py +++ b/src/mkdocstrings_handlers/python/_internal/rendering.py @@ -185,10 +185,12 @@ def do_format_signature( # Pygments sees it as a function call and not a function definition. # The result is that the function name is not parsed as such, # but instead as a regular name: `n` CSS class instead of `nf`. - # To fix it, we replace the first occurrence of an `n` CSS class - # with an `nf` one, unless we found `nf` already. - if signature.find('class="nf"') == -1: - signature = signature.replace('class="n"', 'class="nf"', 1) + # When the function name is a known special name like `__exit__`, + # Pygments will set an `fm` (function -> magic) CSS class. + # To fix this, we replace the CSS class in the first span with `nf`, + # unless we already found an `nf` span. + if not re.search(r'', signature): + signature = re.sub(r'', '', signature, count=1) if stash := env.filters["stash_crossref"].stash: for key, value in stash.items(): diff --git a/tests/snapshots/__init__.py b/tests/snapshots/__init__.py index 556133ac..36eb97b7 100644 --- a/tests/snapshots/__init__.py +++ b/tests/snapshots/__init__.py @@ -8,12 +8,12 @@ ("separate_signature", True), ("show_signature_annotations", False), ("signature_crossrefs", False), - ): external("4370d843cc76*.html"), + ): external("d03d16d1919a*.html"), ( ("separate_signature", True), ("show_signature_annotations", True), ("signature_crossrefs", True), - ): external("261a38d7a86b*.html"), + ): external("e412376be64f*.html"), ( ("separate_signature", False), ("show_signature_annotations", True), @@ -33,12 +33,12 @@ ("separate_signature", True), ("show_signature_annotations", True), ("signature_crossrefs", False), - ): external("f5ce06acbb7a*.html"), + ): external("74ee37cd1e94*.html"), ( ("separate_signature", True), ("show_signature_annotations", False), ("signature_crossrefs", True), - ): external("9c0bfc0ee407*.html"), + ): external("4041a38e355f*.html"), ( ("separate_signature", False), ("show_signature_annotations", True), diff --git a/tests/snapshots/external/9c0bfc0ee40732505dc3dab8c95ad4ed6582d10df2449c7d92f1e43a91610666.html b/tests/snapshots/external/4041a38e355f6585a7e1265509d7c5b499fe3776aeeeb298db7589bb385ca019.html similarity index 93% rename from tests/snapshots/external/9c0bfc0ee40732505dc3dab8c95ad4ed6582d10df2449c7d92f1e43a91610666.html rename to tests/snapshots/external/4041a38e355f6585a7e1265509d7c5b499fe3776aeeeb298db7589bb385ca019.html index 6dd48d30..8454da6d 100644 --- a/tests/snapshots/external/9c0bfc0ee40732505dc3dab8c95ad4ed6582d10df2449c7d92f1e43a91610666.html +++ b/tests/snapshots/external/4041a38e355f6585a7e1265509d7c5b499fe3776aeeeb298db7589bb385ca019.html @@ -36,7 +36,7 @@

- 
__init__(a, b)
+        
__init__(a, b)
diff --git a/tests/snapshots/external/f5ce06acbb7a31658cc6367db31caaf7a210c0a31e71de950e791c5eb33a6258.html b/tests/snapshots/external/74ee37cd1e94250baa33050af088e7341495708d879ab45ee9e8ab1dcac26f2a.html similarity index 89% rename from tests/snapshots/external/f5ce06acbb7a31658cc6367db31caaf7a210c0a31e71de950e791c5eb33a6258.html rename to tests/snapshots/external/74ee37cd1e94250baa33050af088e7341495708d879ab45ee9e8ab1dcac26f2a.html index 08ae8776..9edcf4c5 100644 --- a/tests/snapshots/external/f5ce06acbb7a31658cc6367db31caaf7a210c0a31e71de950e791c5eb33a6258.html +++ b/tests/snapshots/external/74ee37cd1e94250baa33050af088e7341495708d879ab45ee9e8ab1dcac26f2a.html @@ -36,7 +36,7 @@

- 
__init__(a: int, b: str) -> None
+        
__init__(a: int, b: str) -> None
diff --git a/tests/snapshots/external/4370d843cc76138927502402ac39c80414c8441a962f6466afdb280dc022af26.html b/tests/snapshots/external/d03d16d1919af01db9b8d4e5bf36b007810eb3730a7283624a4d68c6fe2ce652.html similarity index 93% rename from tests/snapshots/external/4370d843cc76138927502402ac39c80414c8441a962f6466afdb280dc022af26.html rename to tests/snapshots/external/d03d16d1919af01db9b8d4e5bf36b007810eb3730a7283624a4d68c6fe2ce652.html index c70d8ae8..03d9e14d 100644 --- a/tests/snapshots/external/4370d843cc76138927502402ac39c80414c8441a962f6466afdb280dc022af26.html +++ b/tests/snapshots/external/d03d16d1919af01db9b8d4e5bf36b007810eb3730a7283624a4d68c6fe2ce652.html @@ -36,7 +36,7 @@

- 
__init__(a, b)
+        
__init__(a, b)
diff --git a/tests/snapshots/external/261a38d7a86b5e959b6d1c165108301963d0170c2189d5aa18bb7c7eade84ea4.html b/tests/snapshots/external/e412376be64f25f3f5d2264400a83a1e693c146feec7c359855c676c4a586392.html similarity index 85% rename from tests/snapshots/external/261a38d7a86b5e959b6d1c165108301963d0170c2189d5aa18bb7c7eade84ea4.html rename to tests/snapshots/external/e412376be64f25f3f5d2264400a83a1e693c146feec7c359855c676c4a586392.html index 2170787f..e9ac18ce 100644 --- a/tests/snapshots/external/261a38d7a86b5e959b6d1c165108301963d0170c2189d5aa18bb7c7eade84ea4.html +++ b/tests/snapshots/external/e412376be64f25f3f5d2264400a83a1e693c146feec7c359855c676c4a586392.html @@ -36,7 +36,7 @@

- 
__init__(a: int, b: str) -> None
+        
__init__(a: int, b: str) -> None
From 5d2ba0aa557f683c3f7338d61810034c9af4ab11 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Sat, 24 May 2025 12:35:37 +0200 Subject: [PATCH 07/13] chore: Prepare release 1.16.11 --- CHANGELOG.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8798a05a..b01d34c8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,18 @@ 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). +## [1.16.11](https://github.com/mkdocstrings/python/releases/tag/1.16.11) - 2025-05-24 + +[Compare with 1.16.10](https://github.com/mkdocstrings/python/compare/1.16.10...1.16.11) + +### Bug Fixes + +- Fix highlighting for signature with known special names like `__init__` ([7f95686](https://github.com/mkdocstrings/python/commit/7f956868f93a766346455fedb296c26787894d5c) by Timothée Mazzucotelli). [Issue-mkdocstrings-757](https://github.com/mkdocstrings/mkdocstrings/issues/757) +- Use default font-size for parameter headings ([0a35b20](https://github.com/mkdocstrings/python/commit/0a35b20a6050a28ba8492d93e5f9940a69462ce3) by Timothée Mazzucotelli). [Issue-mkdocstrings-697](https://github.com/mkdocstrings/mkdocstrings/issues/697) +- Prevent uppercasing H5 titles (by Material for MkDocs) ([ba66969](https://github.com/mkdocstrings/python/commit/ba669697daad5067ea5db3fdf8a2d5ba2f966b25) by Timothée Mazzucotelli). [Issue-mkdocstrings-697](https://github.com/mkdocstrings/mkdocstrings/issues/697), [Issue-276](https://github.com/mkdocstrings/python/issues/276) +- Use configured heading even when signature is not separated ([096960a](https://github.com/mkdocstrings/python/commit/096960abd79831d6fd45e2a7962dfd2bd49e4edd) by Timothée Mazzucotelli). [Issue-mkdocstrings-767](https://github.com/mkdocstrings/mkdocstrings/issues/767), [PR-278](https://github.com/mkdocstrings/python/pull/278) +- Render attribute names without full path in ToC ([d4e618a](https://github.com/mkdocstrings/python/commit/d4e618ab794747b84dced848b1be824639fea2b8) by David Lee). [Issue-271](https://github.com/mkdocstrings/python/issues/271), [PR-272](https://github.com/mkdocstrings/python/pull/272) + ## [1.16.10](https://github.com/mkdocstrings/python/releases/tag/1.16.10) - 2025-04-03 [Compare with 1.16.9](https://github.com/mkdocstrings/python/compare/1.16.9...1.16.10) From d57740f874f056fb3ba1c6013ad04227df0f0af8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Mon, 2 Jun 2025 13:38:20 +0200 Subject: [PATCH 08/13] fix: Only replace CSS class in first *highlighting* span When `pymdownx.highlight` sets `auto_title: true`, another span is rendered before the highlighted code. If we replace its CSS class, we mess its final display. Our solution is not very robust: we only look for spans with CSS classes of 1 or 2 characters instead of 1 or more characters. Issue-281: https://github.com/mkdocstrings/python/issues/281 --- src/mkdocstrings_handlers/python/_internal/rendering.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/mkdocstrings_handlers/python/_internal/rendering.py b/src/mkdocstrings_handlers/python/_internal/rendering.py index 902d794e..897b6572 100644 --- a/src/mkdocstrings_handlers/python/_internal/rendering.py +++ b/src/mkdocstrings_handlers/python/_internal/rendering.py @@ -190,7 +190,7 @@ def do_format_signature( # To fix this, we replace the CSS class in the first span with `nf`, # unless we already found an `nf` span. if not re.search(r'', signature): - signature = re.sub(r'', '', signature, count=1) + signature = re.sub(r'', '', signature, count=1) if stash := env.filters["stash_crossref"].stash: for key, value in stash.items(): From 3c4424d4ff63dacb6e4bf4e7a8c462ea377fb1a8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Tue, 3 Jun 2025 14:52:03 +0200 Subject: [PATCH 09/13] chore: Prepare release 1.16.12 --- CHANGELOG.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index b01d34c8..ea4f1cf3 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,14 @@ 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). +## [1.16.12](https://github.com/mkdocstrings/python/releases/tag/1.16.12) - 2025-06-03 + +[Compare with 1.16.11](https://github.com/mkdocstrings/python/compare/1.16.11...1.16.12) + +### Bug Fixes + +- Only replace CSS class in first *highlighting* span ([d57740f](https://github.com/mkdocstrings/python/commit/d57740f874f056fb3ba1c6013ad04227df0f0af8) by Timothée Mazzucotelli). [Issue-281](https://github.com/mkdocstrings/python/issues/281) + ## [1.16.11](https://github.com/mkdocstrings/python/releases/tag/1.16.11) - 2025-05-24 [Compare with 1.16.10](https://github.com/mkdocstrings/python/compare/1.16.10...1.16.11) From bac553d8bd87c2ca9a1cd67fc473e2686a4eedc2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Tue, 3 Jun 2025 15:09:00 +0200 Subject: [PATCH 10/13] ci: Type variable to satisfy Mypy --- src/mkdocstrings_handlers/python/_internal/handler.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/mkdocstrings_handlers/python/_internal/handler.py b/src/mkdocstrings_handlers/python/_internal/handler.py index 896a70e3..158d7ddc 100644 --- a/src/mkdocstrings_handlers/python/_internal/handler.py +++ b/src/mkdocstrings_handlers/python/_internal/handler.py @@ -360,7 +360,7 @@ def get_aliases(self, identifier: str) -> tuple[str, ...]: return tuple(f"{alias}({parameter})" for alias in aliases) return tuple(aliases) - def normalize_extension_paths(self, extensions: Sequence) -> Sequence: + def normalize_extension_paths(self, extensions: Sequence) -> list[str | dict[str, Any]]: """Resolve extension paths relative to config file. Parameters: @@ -369,7 +369,7 @@ def normalize_extension_paths(self, extensions: Sequence) -> Sequence: Returns: The normalized extensions. """ - normalized = [] + normalized: list[str | dict[str, Any]] = [] for ext in extensions: if isinstance(ext, dict): From f2b3bb07c52c967ad93452015f2dbdc54383ecaf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Timoth=C3=A9e=20Mazzucotelli?= Date: Tue, 1 Jul 2025 19:05:53 +0200 Subject: [PATCH 11/13] ci: Fix Ruff warnings --- duties.py | 2 +- src/mkdocstrings_handlers/python/_internal/rendering.py | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/duties.py b/duties.py index 18282747..2f09340f 100644 --- a/duties.py +++ b/duties.py @@ -240,7 +240,7 @@ def coverage(ctx: Context) -> None: @duty -def test(ctx: Context, *cli_args: str, match: str = "", snapshot: str = "report") -> None: +def test(ctx: Context, *cli_args: str, match: str = "", snapshot: str = "report") -> None: # noqa: PT028 """Run the test suite. Parameters: diff --git a/src/mkdocstrings_handlers/python/_internal/rendering.py b/src/mkdocstrings_handlers/python/_internal/rendering.py index 897b6572..ce701114 100644 --- a/src/mkdocstrings_handlers/python/_internal/rendering.py +++ b/src/mkdocstrings_handlers/python/_internal/rendering.py @@ -261,7 +261,7 @@ def do_format_attribute( def do_order_members( members: Sequence[Object | Alias], order: Order | list[Order], - members_list: bool | list[str] | None, + members_list: bool | list[str] | None, # noqa: FBT001 ) -> Sequence[Object | Alias]: """Order members given an ordering method. @@ -522,7 +522,7 @@ def _get_formatter() -> Callable[[str, int], str]: def _get_ruff_formatter() -> Callable[[str, int], str] | None: try: - from ruff.__main__ import find_ruff_bin + from ruff.__main__ import find_ruff_bin # noqa: PLC0415 except ImportError: return None @@ -558,7 +558,7 @@ def formatter(code: str, line_length: int) -> str: def _get_black_formatter() -> Callable[[str, int], str] | None: try: - from black import InvalidInput, Mode, format_str + from black import InvalidInput, Mode, format_str # noqa: PLC0415 except ModuleNotFoundError: return None From d3b35e17384901e7280b8b6926f10fb033480358 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bartosz=20S=C5=82awecki?= Date: Thu, 3 Jul 2025 16:31:31 +0200 Subject: [PATCH 12/13] feat: Support hiding implementation signature (showing overload only) Issue-213: https://github.com/mkdocstrings/python/issues/213 PR-286: https://github.com/mkdocstrings/python/pull/286 --- docs/usage/configuration/signatures.md | 50 +++++ .../python/_internal/config.py | 8 + .../material/_base/function.html.jinja | 2 +- tests/snapshots/__init__.py | 24 +++ ...805c6c2488b30461055f427156fa1567e51c1.html | 169 ++++++++++++++++ ...90888add55a0ff86d8932191bb726ebe1c443.html | 137 +++++++++++++ ...69808d0f3b67e28b1677f04ab965d1da2e6b3.html | 189 ++++++++++++++++++ ...dad2b07086db09c903a750af2f6be914fffb4.html | 189 ++++++++++++++++++ ...310b459b913f30b1bce149d805322d136c711.html | 169 ++++++++++++++++ ...260beecc355aaf82cd133e082e37883837002.html | 117 +++++++++++ ...7d37c09ec0b0294020d9337f34887d02590b5.html | 117 +++++++++++ ...1ab6f69201b959d606633320c9d53d2b3298b.html | 129 ++++++++++++ tests/test_end_to_end.py | 63 ++++++ 13 files changed, 1362 insertions(+), 1 deletion(-) create mode 100644 tests/snapshots/external/17e520187500b8d5538f3bbef11805c6c2488b30461055f427156fa1567e51c1.html create mode 100644 tests/snapshots/external/19a1066a31c46587271239553fc90888add55a0ff86d8932191bb726ebe1c443.html create mode 100644 tests/snapshots/external/30b2733496a882fe6d5d71107eb69808d0f3b67e28b1677f04ab965d1da2e6b3.html create mode 100644 tests/snapshots/external/35c8879435c018f36b85b8167e3dad2b07086db09c903a750af2f6be914fffb4.html create mode 100644 tests/snapshots/external/45fa32980cabc490537069f05a1310b459b913f30b1bce149d805322d136c711.html create mode 100644 tests/snapshots/external/728ef9e28d866a04e6cd10c1c1c260beecc355aaf82cd133e082e37883837002.html create mode 100644 tests/snapshots/external/90ca219874af369f47b226128197d37c09ec0b0294020d9337f34887d02590b5.html create mode 100644 tests/snapshots/external/fca9fb3aa9f566962016f8042811ab6f69201b959d606633320c9d53d2b3298b.html diff --git a/docs/usage/configuration/signatures.md b/docs/usage/configuration/signatures.md index 98c865e5..225be0b8 100644 --- a/docs/usage/configuration/signatures.md +++ b/docs/usage/configuration/signatures.md @@ -286,6 +286,56 @@ plugins: /// +[](){#option-overloads_only} +## `overloads_only` + +Whether to hide the implementation signature if the overloads are shown with [`show_overloads`][]. + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + overloads_only: true +``` + +```md title="or in docs/some_page.md (local configuration)" +::: path.to.module + options: + overloads_only: true +``` + +/// admonition | Preview + type: preview +//// tab | With overloads only +

function

+ +```python +@overload +function(param1: int): ... +@overload +function(param1: str): ... +``` +Function docstring. + +//// +//// tab | Without overloads only +

function

+ +```python +@overload +function(param1: int): ... +@overload +function(param1: str): ... +function(param1: str | int) +``` +Function docstring. + +//// + +/// + [](){#option-show_signature} ## `show_signature` diff --git a/src/mkdocstrings_handlers/python/_internal/config.py b/src/mkdocstrings_handlers/python/_internal/config.py index 210f8fe2..5c754088 100644 --- a/src/mkdocstrings_handlers/python/_internal/config.py +++ b/src/mkdocstrings_handlers/python/_internal/config.py @@ -554,6 +554,14 @@ class PythonInputOptions: ), ] = False + overloads_only: Annotated[ + bool, + _Field( + group="signatures", + description="Whether to hide the implementation signature if the overloads are shown.", + ), + ] = False + parameter_headings: Annotated[ bool, _Field( diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja index 21888939..cd97c8db 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/function.html.jinja @@ -94,7 +94,7 @@ Context: {% endfor %}
{% endif %} - {% if config.separate_signature %} + {% if config.separate_signature and not (config.show_overloads and function.overloads and config.overloads_only) %} {% filter format_signature(function, config.line_length, crossrefs=config.signature_crossrefs) %} {{ function.name }} {% endfilter %} diff --git a/tests/snapshots/__init__.py b/tests/snapshots/__init__.py index 36eb97b7..f79db237 100644 --- a/tests/snapshots/__init__.py +++ b/tests/snapshots/__init__.py @@ -44,6 +44,30 @@ ("show_signature_annotations", True), ("signature_crossrefs", False), ): external("d1216ebf8e30*.html"), + (("overloads_only", False), ("separate_signature", True), ("show_overloads", True)): external( + "19a1066a31c4*.html", + ), + (("overloads_only", False), ("separate_signature", True), ("show_overloads", False)): external( + "728ef9e28d86*.html", + ), + (("overloads_only", True), ("separate_signature", False), ("show_overloads", True)): external( + "30b2733496a8*.html", + ), + (("overloads_only", False), ("separate_signature", False), ("show_overloads", True)): external( + "35c8879435c0*.html", + ), + (("overloads_only", False), ("separate_signature", False), ("show_overloads", False)): external( + "45fa32980cab*.html", + ), + (("overloads_only", True), ("separate_signature", True), ("show_overloads", False)): external( + "90ca219874af*.html", + ), + (("overloads_only", True), ("separate_signature", True), ("show_overloads", True)): external( + "fca9fb3aa9f5*.html", + ), + (("overloads_only", True), ("separate_signature", False), ("show_overloads", False)): external( + "17e520187500*.html", + ), }, ) diff --git a/tests/snapshots/external/17e520187500b8d5538f3bbef11805c6c2488b30461055f427156fa1567e51c1.html b/tests/snapshots/external/17e520187500b8d5538f3bbef11805c6c2488b30461055f427156fa1567e51c1.html new file mode 100644 index 00000000..23a1a9c5 --- /dev/null +++ b/tests/snapshots/external/17e520187500b8d5538f3bbef11805c6c2488b30461055f427156fa1567e51c1.html @@ -0,0 +1,169 @@ + + +
+

+ + overloads_package + +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + + bar + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.bar + + . +

+
+
+
+

+ + + foo + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.foo + + . +

+
+
+
+
+
+
+

+ + + bar + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + bar + + . +

+
+
+
+

+ + + foo + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + foo + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/19a1066a31c46587271239553fc90888add55a0ff86d8932191bb726ebe1c443.html b/tests/snapshots/external/19a1066a31c46587271239553fc90888add55a0ff86d8932191bb726ebe1c443.html new file mode 100644 index 00000000..3f231581 --- /dev/null +++ b/tests/snapshots/external/19a1066a31c46587271239553fc90888add55a0ff86d8932191bb726ebe1c443.html @@ -0,0 +1,137 @@ + + +
+

+ + overloads_package + +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + bar + +

+
+ 
bar(a, b)
+
+
+
+

+ Docstring for + + Class.bar + + . +

+
+
+
+

+ + foo + +

+
+
+ 
foo(a: int, b: str) -> float
+
+
+
+ 
foo(a: str, b: int) -> None
+
+
+
+
+ 
foo(a, b)
+
+
+
+

+ Docstring for + + Class.foo + + . +

+
+
+
+
+
+
+

+ + bar + +

+
+ 
bar(a, b)
+
+
+
+

+ Docstring for + + bar + + . +

+
+
+
+

+ + foo + +

+
+
+ 
foo(a: int, b: str) -> float
+
+
+
+ 
foo(a: str, b: int) -> None
+
+
+
+
+ 
foo(a, b)
+
+
+
+

+ Docstring for + + foo + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/30b2733496a882fe6d5d71107eb69808d0f3b67e28b1677f04ab965d1da2e6b3.html b/tests/snapshots/external/30b2733496a882fe6d5d71107eb69808d0f3b67e28b1677f04ab965d1da2e6b3.html new file mode 100644 index 00000000..79b078af --- /dev/null +++ b/tests/snapshots/external/30b2733496a882fe6d5d71107eb69808d0f3b67e28b1677f04ab965d1da2e6b3.html @@ -0,0 +1,189 @@ + + +
+

+ + overloads_package + +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + + bar + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.bar + + . +

+
+
+
+

+ + + foo + + + ( + + + a + + + , + + + b + + + ) + + +

+
+
+ 
foo(a: int, b: str) -> float
+
+
+
+ 
foo(a: str, b: int) -> None
+
+
+
+
+

+ Docstring for + + Class.foo + + . +

+
+
+
+
+
+
+

+ + + bar + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + bar + + . +

+
+
+
+

+ + + foo + + + ( + + + a + + + , + + + b + + + ) + + +

+
+
+ 
foo(a: int, b: str) -> float
+
+
+
+ 
foo(a: str, b: int) -> None
+
+
+
+
+

+ Docstring for + + foo + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/35c8879435c018f36b85b8167e3dad2b07086db09c903a750af2f6be914fffb4.html b/tests/snapshots/external/35c8879435c018f36b85b8167e3dad2b07086db09c903a750af2f6be914fffb4.html new file mode 100644 index 00000000..afa94fae --- /dev/null +++ b/tests/snapshots/external/35c8879435c018f36b85b8167e3dad2b07086db09c903a750af2f6be914fffb4.html @@ -0,0 +1,189 @@ + + +
+

+ + overloads_package + +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + + bar + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.bar + + . +

+
+
+
+

+ + + foo + + + ( + + + a + + + , + + + b + + + ) + + +

+
+
+ 
foo(a: int, b: str) -> float
+
+
+
+ 
foo(a: str, b: int) -> None
+
+
+
+
+

+ Docstring for + + Class.foo + + . +

+
+
+
+
+
+
+

+ + + bar + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + bar + + . +

+
+
+
+

+ + + foo + + + ( + + + a + + + , + + + b + + + ) + + +

+
+
+ 
foo(a: int, b: str) -> float
+
+
+
+ 
foo(a: str, b: int) -> None
+
+
+
+
+

+ Docstring for + + foo + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/45fa32980cabc490537069f05a1310b459b913f30b1bce149d805322d136c711.html b/tests/snapshots/external/45fa32980cabc490537069f05a1310b459b913f30b1bce149d805322d136c711.html new file mode 100644 index 00000000..76234631 --- /dev/null +++ b/tests/snapshots/external/45fa32980cabc490537069f05a1310b459b913f30b1bce149d805322d136c711.html @@ -0,0 +1,169 @@ + + +
+

+ + overloads_package + +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + + bar + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.bar + + . +

+
+
+
+

+ + + foo + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + Class.foo + + . +

+
+
+
+
+
+
+

+ + + bar + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + bar + + . +

+
+
+
+

+ + + foo + + + ( + + + a + + + , + + + b + + + ) + + +

+
+

+ Docstring for + + foo + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/728ef9e28d866a04e6cd10c1c1c260beecc355aaf82cd133e082e37883837002.html b/tests/snapshots/external/728ef9e28d866a04e6cd10c1c1c260beecc355aaf82cd133e082e37883837002.html new file mode 100644 index 00000000..96629ba3 --- /dev/null +++ b/tests/snapshots/external/728ef9e28d866a04e6cd10c1c1c260beecc355aaf82cd133e082e37883837002.html @@ -0,0 +1,117 @@ + + +
+

+ + overloads_package + +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + bar + +

+
+ 
bar(a, b)
+
+
+
+

+ Docstring for + + Class.bar + + . +

+
+
+
+

+ + foo + +

+
+ 
foo(a, b)
+
+
+
+

+ Docstring for + + Class.foo + + . +

+
+
+
+
+
+
+

+ + bar + +

+
+ 
bar(a, b)
+
+
+
+

+ Docstring for + + bar + + . +

+
+
+
+

+ + foo + +

+
+ 
foo(a, b)
+
+
+
+

+ Docstring for + + foo + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/90ca219874af369f47b226128197d37c09ec0b0294020d9337f34887d02590b5.html b/tests/snapshots/external/90ca219874af369f47b226128197d37c09ec0b0294020d9337f34887d02590b5.html new file mode 100644 index 00000000..1f1c5822 --- /dev/null +++ b/tests/snapshots/external/90ca219874af369f47b226128197d37c09ec0b0294020d9337f34887d02590b5.html @@ -0,0 +1,117 @@ + + +
+

+ + overloads_package + +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + bar + +

+
+ 
bar(a, b)
+
+
+
+

+ Docstring for + + Class.bar + + . +

+
+
+
+

+ + foo + +

+
+ 
foo(a, b)
+
+
+
+

+ Docstring for + + Class.foo + + . +

+
+
+
+
+
+
+

+ + bar + +

+
+ 
bar(a, b)
+
+
+
+

+ Docstring for + + bar + + . +

+
+
+
+

+ + foo + +

+
+ 
foo(a, b)
+
+
+
+

+ Docstring for + + foo + + . +

+
+
+
+
+
diff --git a/tests/snapshots/external/fca9fb3aa9f566962016f8042811ab6f69201b959d606633320c9d53d2b3298b.html b/tests/snapshots/external/fca9fb3aa9f566962016f8042811ab6f69201b959d606633320c9d53d2b3298b.html new file mode 100644 index 00000000..7d4b3416 --- /dev/null +++ b/tests/snapshots/external/fca9fb3aa9f566962016f8042811ab6f69201b959d606633320c9d53d2b3298b.html @@ -0,0 +1,129 @@ + + +
+

+ + overloads_package + +

+
+
+
+

+ + Class + +

+
+

+ Docstring for + + Class + + . +

+
+
+

+ + bar + +

+
+ 
bar(a, b)
+
+
+
+

+ Docstring for + + Class.bar + + . +

+
+
+
+

+ + foo + +

+
+
+ 
foo(a: int, b: str) -> float
+
+
+
+ 
foo(a: str, b: int) -> None
+
+
+
+
+

+ Docstring for + + Class.foo + + . +

+
+
+
+
+
+
+

+ + bar + +

+
+ 
bar(a, b)
+
+
+
+

+ Docstring for + + bar + + . +

+
+
+
+

+ + foo + +

+
+
+ 
foo(a: int, b: str) -> float
+
+
+
+ 
foo(a: str, b: int) -> None
+
+
+
+
+

+ Docstring for + + foo + + . +

+
+
+
+
+
diff --git a/tests/test_end_to_end.py b/tests/test_end_to_end.py index 3a96f803..4e749432 100644 --- a/tests/test_end_to_end.py +++ b/tests/test_end_to_end.py @@ -108,6 +108,69 @@ def test_end_to_end_for_signatures( assert outsource(html, suffix=".html") == snapshots_signatures[snapshot_key] +# Signature overloads tests. +@pytest.fixture(name="overloads_package", scope="session") +def _overloads_package() -> Iterator[TmpPackage]: + code = """ + from typing_extensions import overload + + @overload + def foo(a: int, b: str) -> float: ... + + @overload + def foo(a: str, b: int) -> None: ... + + def foo(a: str | int, b: int | str) -> float | None: + '''Docstring for `foo`.''' + + def bar(a: str, b: int | str) -> float | None: + '''Docstring for `bar`.''' + + class Class: + '''Docstring for `Class`.''' + + @overload + def foo(self, a: int, b: str) -> float: ... + + @overload + def foo(self, a: str, b: int) -> None: ... + + def foo(self, a: str | int, b: int | str) -> float | None: + '''Docstring for `Class.foo`.''' + + def bar(self, a: str, b: int | str) -> float | None: + '''Docstring for `Class.bar`.''' + """ + with temporary_pypackage("overloads_package", {"__init__.py": code}) as tmppkg: + yield tmppkg + + +@pytest.mark.parametrize("separate_signature", [True, False]) +@pytest.mark.parametrize("show_overloads", [True, False]) +@pytest.mark.parametrize("overloads_only", [True, False]) +def test_end_to_end_for_overloads( + session_handler: PythonHandler, + overloads_package: TmpPackage, + separate_signature: bool, + show_overloads: bool, + overloads_only: bool, +) -> None: + """Test rendering of a given theme's templates. + + Parameters: + identifier: Parametrized identifier. + session_handler: Python handler (fixture). + """ + final_options = { + "separate_signature": separate_signature, + "show_overloads": show_overloads, + "overloads_only": overloads_only, + } + html = _render_options(final_options) + _render(session_handler, overloads_package, final_options) + snapshot_key = tuple(sorted(final_options.items())) + assert outsource(html, suffix=".html") == snapshots_signatures[snapshot_key] + + # Member tests. @pytest.fixture(name="members_package", scope="session") def _members_package() -> Iterator[TmpPackage]: From 6cf34b9882e20d9147a6481e672ae09989a27796 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bartosz=20S=C5=82awecki?= Date: Wed, 9 Jul 2025 22:21:20 +0200 Subject: [PATCH 13/13] feat: Support hiding attribute values Issue-292: #292 PR-293: #293 --- docs/usage/configuration/members.md | 44 +++++++++++++++++++ .../python/_internal/config.py | 8 ++++ .../python/_internal/rendering.py | 3 +- .../material/_base/attribute.html.jinja | 4 +- 4 files changed, 56 insertions(+), 3 deletions(-) diff --git a/docs/usage/configuration/members.md b/docs/usage/configuration/members.md index 7a5069a1..4afdd310 100644 --- a/docs/usage/configuration/members.md +++ b/docs/usage/configuration/members.md @@ -519,6 +519,50 @@ def function_d(): //// /// + +[](){#option-show_attribute_values} +## `show_attribute_values` + +- **:octicons-package-24: Type [`bool`][] :material-equal: `True`{ title="default value" }** + + +Show initial values of attributes in classes. + +```yaml title="in mkdocs.yml (global configuration)" +plugins: +- mkdocstrings: + handlers: + python: + options: + show_attribute_values: true +``` + +```md title="or in docs/some_page.md (local configuration)" +::: path.to.object + options: + show_attribute_values: true +``` + +```python title="package/module.py" +class SomeClass: + def __init__(self): + self.some_attr = 1 +``` + +/// admonition | Preview + type: preview + +//// tab | With attribute values visible +

SomeClass

+

some_attr = 1

+//// + +//// tab | With attribute values hidden +

SomeClass

+

some_attr

+//// +/// + [](){#option-show_submodules} ## `show_submodules` diff --git a/src/mkdocstrings_handlers/python/_internal/config.py b/src/mkdocstrings_handlers/python/_internal/config.py index 5c754088..5565e9b0 100644 --- a/src/mkdocstrings_handlers/python/_internal/config.py +++ b/src/mkdocstrings_handlers/python/_internal/config.py @@ -622,6 +622,14 @@ class PythonInputOptions: ), ] = False + show_attribute_values: Annotated[ + bool, + _Field( + group="members", + description="Show initial values of attributes in classes.", + ), + ] = True + show_bases: Annotated[ bool, _Field( diff --git a/src/mkdocstrings_handlers/python/_internal/rendering.py b/src/mkdocstrings_handlers/python/_internal/rendering.py index ce701114..70eacb36 100644 --- a/src/mkdocstrings_handlers/python/_internal/rendering.py +++ b/src/mkdocstrings_handlers/python/_internal/rendering.py @@ -208,6 +208,7 @@ def do_format_attribute( line_length: int, *, crossrefs: bool = False, # noqa: ARG001 + show_value: bool = True, ) -> str: """Format an attribute. @@ -235,7 +236,7 @@ def do_format_attribute( backlink_type="returned-by", ) signature += f": {annotation}" - if attribute.value: + if show_value and attribute.value: value = template.render(context.parent, expression=attribute.value, signature=True, backlink_type="used-by") signature += f" = {value}" diff --git a/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja index 519590e5..5832c8bd 100644 --- a/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja +++ b/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja @@ -55,7 +55,7 @@ Context: {% else %} {%+ filter highlight(language="python", inline=True) %} {{ attribute_name }}{% if attribute.annotation and config.show_signature_annotations %}: {{ attribute.annotation }}{% endif %} - {% if attribute.value %} = {{ attribute.value }}{% endif %} + {% if config.show_attribute_values and attribute.value %} = {{ attribute.value }}{% endif %} {% endfilter %} {% endif %} {% endblock heading %} @@ -79,7 +79,7 @@ Context: This block renders the signature for the attribute. -#} {% if config.separate_signature %} - {% filter format_attribute(attribute, config.line_length, crossrefs=config.signature_crossrefs) %} + {% filter format_attribute(attribute, config.line_length, crossrefs=config.signature_crossrefs, show_value=config.show_attribute_values) %} {{ attribute.name }} {% endfilter %} {% endif %}