From a2399c0fc1c57e9a3d51c4594a5cd1fbcfe4475c Mon Sep 17 00:00:00 2001 From: Maciej Olko Date: Sun, 2 Feb 2025 21:45:27 +0100 Subject: [PATCH 1/7] Docs: allow translation of a phrase in availability directive --- Doc/tools/extensions/availability.py | 20 ++++++++++++++++++-- Doc/tools/templates/dummy.html | 1 + 2 files changed, 19 insertions(+), 2 deletions(-) diff --git a/Doc/tools/extensions/availability.py b/Doc/tools/extensions/availability.py index 1a2c7b02b44439..a391e1dc840617 100644 --- a/Doc/tools/extensions/availability.py +++ b/Doc/tools/extensions/availability.py @@ -2,6 +2,7 @@ from __future__ import annotations +from itertools import starmap from typing import TYPE_CHECKING from docutils import nodes @@ -11,6 +12,8 @@ from sphinx.util.docutils import SphinxDirective if TYPE_CHECKING: + from collections.abc import Callable + from sphinx.application import Sphinx from sphinx.util.typing import ExtensionMetadata @@ -49,6 +52,16 @@ KNOWN_PLATFORMS = _PLATFORMS | _LIBC | _THREADING +def _print_platform( + platform: str, version: str | bool +) -> str | Callable[[str], str]: + if version is True: + return platform + if not version: + return sphinx_gettext("not {platform}").format(platform=platform) + return f"{platform} >= {version}" + + class Availability(SphinxDirective): has_content = True required_arguments = 1 @@ -68,14 +81,17 @@ def run(self) -> list[nodes.container]: refwarn=True, ) sep = nodes.Text(": ") - parsed, msgs = self.state.inline_text(self.arguments[0], self.lineno) + platforms = self.parse_platforms() + platforms_text = ( + f"{', '.join(starmap(_print_platform, platforms.items()))}." + ) + parsed, msgs = self.state.inline_text(platforms_text, self.lineno) pnode = nodes.paragraph(title, "", refnode, sep, *parsed, *msgs) self.set_source_info(pnode) cnode = nodes.container("", pnode, classes=["availability"]) self.set_source_info(cnode) if self.content: self.state.nested_parse(self.content, self.content_offset, cnode) - self.parse_platforms() return [cnode] diff --git a/Doc/tools/templates/dummy.html b/Doc/tools/templates/dummy.html index 4f0f6f91436a87..c1079ebf9d3a74 100644 --- a/Doc/tools/templates/dummy.html +++ b/Doc/tools/templates/dummy.html @@ -10,6 +10,7 @@ In extensions/availability.py: {% trans %}Availability{% endtrans %} +{% trans %}not {platform}{% endtrans %} In extensions/c_annotations.py: From 8de15ea1ebc8aa2f3bbaa50f342582af7cd4cab9 Mon Sep 17 00:00:00 2001 From: Maciej Olko Date: Sun, 2 Feb 2025 21:52:39 +0100 Subject: [PATCH 2/7] Use greater-than or equal-to character --- Doc/tools/extensions/availability.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/tools/extensions/availability.py b/Doc/tools/extensions/availability.py index a391e1dc840617..79544a09affe8c 100644 --- a/Doc/tools/extensions/availability.py +++ b/Doc/tools/extensions/availability.py @@ -59,7 +59,7 @@ def _print_platform( return platform if not version: return sphinx_gettext("not {platform}").format(platform=platform) - return f"{platform} >= {version}" + return f"{platform} ≥ {version}" class Availability(SphinxDirective): From c9ee08d1f23b4113d2730816885d5de19f82ad9c Mon Sep 17 00:00:00 2001 From: Maciej Olko Date: Mon, 3 Feb 2025 00:03:28 +0100 Subject: [PATCH 3/7] Refactor: move helper function down --- Doc/tools/extensions/availability.py | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/Doc/tools/extensions/availability.py b/Doc/tools/extensions/availability.py index 79544a09affe8c..4096d4352e7768 100644 --- a/Doc/tools/extensions/availability.py +++ b/Doc/tools/extensions/availability.py @@ -52,16 +52,6 @@ KNOWN_PLATFORMS = _PLATFORMS | _LIBC | _THREADING -def _print_platform( - platform: str, version: str | bool -) -> str | Callable[[str], str]: - if version is True: - return platform - if not version: - return sphinx_gettext("not {platform}").format(platform=platform) - return f"{platform} ≥ {version}" - - class Availability(SphinxDirective): has_content = True required_arguments = 1 @@ -132,6 +122,16 @@ def parse_platforms(self) -> dict[str, str | bool]: return platforms +def _print_platform( + platform: str, version: str | bool +) -> str | Callable[[str], str]: + if version is True: + return platform + if not version: + return sphinx_gettext("not {platform}").format(platform=platform) + return f"{platform} ≥ {version}" + + def setup(app: Sphinx) -> ExtensionMetadata: app.add_directive("availability", Availability) From 88a9a9e4c95ad742b031592c14358b3b30dbef9f Mon Sep 17 00:00:00 2001 From: Maciej Olko Date: Mon, 3 Feb 2025 00:05:08 +0100 Subject: [PATCH 4/7] Fix type annotations --- Doc/tools/extensions/availability.py | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/Doc/tools/extensions/availability.py b/Doc/tools/extensions/availability.py index 4096d4352e7768..8a66c024d66a34 100644 --- a/Doc/tools/extensions/availability.py +++ b/Doc/tools/extensions/availability.py @@ -12,8 +12,6 @@ from sphinx.util.docutils import SphinxDirective if TYPE_CHECKING: - from collections.abc import Callable - from sphinx.application import Sphinx from sphinx.util.typing import ExtensionMetadata @@ -122,9 +120,7 @@ def parse_platforms(self) -> dict[str, str | bool]: return platforms -def _print_platform( - platform: str, version: str | bool -) -> str | Callable[[str], str]: +def _print_platform(platform: str, version: str | bool) -> str: if version is True: return platform if not version: From e6fe49e867e1c9098b67187684c2f446005e7860 Mon Sep 17 00:00:00 2001 From: Maciej Olko Date: Mon, 3 Feb 2025 01:52:12 +0100 Subject: [PATCH 5/7] Use Babel's format_list() --- Doc/tools/extensions/availability.py | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/Doc/tools/extensions/availability.py b/Doc/tools/extensions/availability.py index 8a66c024d66a34..d74790becc05c8 100644 --- a/Doc/tools/extensions/availability.py +++ b/Doc/tools/extensions/availability.py @@ -5,6 +5,7 @@ from itertools import starmap from typing import TYPE_CHECKING +from babel.lists import format_list from docutils import nodes from sphinx import addnodes from sphinx.locale import _ as sphinx_gettext @@ -70,9 +71,7 @@ def run(self) -> list[nodes.container]: ) sep = nodes.Text(": ") platforms = self.parse_platforms() - platforms_text = ( - f"{', '.join(starmap(_print_platform, platforms.items()))}." - ) + platforms_text = f"{format_list(list(starmap(_print_platform, platforms.items())), locale=self.config.language)}." parsed, msgs = self.state.inline_text(platforms_text, self.lineno) pnode = nodes.paragraph(title, "", refnode, sep, *parsed, *msgs) self.set_source_info(pnode) From 2cb41d9cce421350528cb6f2151948e2a4a4f772 Mon Sep 17 00:00:00 2001 From: Maciej Olko Date: Mon, 3 Feb 2025 22:40:24 +0100 Subject: [PATCH 6/7] Rename _print_platform() to _format_platform() Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- Doc/tools/extensions/availability.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/tools/extensions/availability.py b/Doc/tools/extensions/availability.py index d74790becc05c8..ef6c45566bc8e6 100644 --- a/Doc/tools/extensions/availability.py +++ b/Doc/tools/extensions/availability.py @@ -119,7 +119,7 @@ def parse_platforms(self) -> dict[str, str | bool]: return platforms -def _print_platform(platform: str, version: str | bool) -> str: +def _format_platform(platform: str, version: str | bool) -> str: if version is True: return platform if not version: From f273e6edd9a08953d133b726bb0f18b9025f9bae Mon Sep 17 00:00:00 2001 From: Maciej Olko Date: Mon, 3 Feb 2025 22:40:56 +0100 Subject: [PATCH 7/7] Rename formatting function in a call Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- Doc/tools/extensions/availability.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/tools/extensions/availability.py b/Doc/tools/extensions/availability.py index ef6c45566bc8e6..dfafaf2da245ba 100644 --- a/Doc/tools/extensions/availability.py +++ b/Doc/tools/extensions/availability.py @@ -71,7 +71,7 @@ def run(self) -> list[nodes.container]: ) sep = nodes.Text(": ") platforms = self.parse_platforms() - platforms_text = f"{format_list(list(starmap(_print_platform, platforms.items())), locale=self.config.language)}." + platforms_text = f"{format_list(list(starmap(_format_platform, platforms.items())), locale=self.config.language)}." parsed, msgs = self.state.inline_text(platforms_text, self.lineno) pnode = nodes.paragraph(title, "", refnode, sep, *parsed, *msgs) self.set_source_info(pnode)