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/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) 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/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/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja b/src/mkdocstrings_handlers/python/templates/material/_base/attribute.html.jinja index 7894c544..519590e5 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 %} @@ -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/src/mkdocstrings_handlers/python/templates/material/style.css b/src/mkdocstrings_handlers/python/templates/material/style.css index e5e150ec..b8c3e639 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 { @@ -30,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; diff --git a/tests/snapshots/__init__.py b/tests/snapshots/__init__.py index e411bfa8..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), @@ -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/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/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/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/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/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
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 + ".") 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]