Skip to content

gh-126609: localize list, allow translation of a phrase, use ge operator character in the availability directive#129597

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
m-aciek wants to merge 7 commits into from
Closed

gh-126609: localize list, allow translation of a phrase, use ge operator character in the availability directive #129597

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
a2399c0
Docs: allow translation of a phrase in availability directive
m-aciek Feb 2, 2025
8de15ea
Use greater-than or equal-to character
m-aciek Feb 2, 2025
c9ee08d
Refactor: move helper function down
m-aciek Feb 2, 2025
88a9a9e
Fix type annotations
m-aciek Feb 2, 2025
e6fe49e
Use Babel's format_list()
m-aciek Feb 3, 2025
2cb41d9
Rename _print_platform() to _format_platform()
m-aciek Feb 3, 2025
f273e6e
Rename formatting function in a call
m-aciek Feb 3, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 13 additions & 2 deletions Doc/tools/extensions/availability.py
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -2,8 +2,10 @@

from __future__ import annotations

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
Expand DownExpand Up@@ -68,14 +70,15 @@ def run(self) -> list[nodes.container]:
refwarn=True,
)
sep = nodes.Text(": ")
parsed, msgs = self.state.inline_text(self.arguments[0], self.lineno)
Copy link
Member

@AA-TurnerAA-TurnerFeb 2, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is somewhat surprising that this doesn't work, as sphinx.util.nodes.extract_messages() should pick up the rawsource attributes -- we shouldn't need to parse & reparse.

Copy link
ContributorAuthor

@m-aciekm-aciekFeb 3, 2025•
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Even when I've added not WASI, not Android. translation string by hand, it wasn't picked up in the build process.

platforms = self.parse_platforms()
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)
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]

Expand DownExpand Up@@ -116,6 +119,14 @@ def parse_platforms(self) -> dict[str, str | bool]:
return platforms


def _format_platform(platform: str, version: str | bool) -> str:
if version is True:
return platform
if not version:
return sphinx_gettext("not{platform}").format(platform=platform)
return f"{platform} ≥{version}"
Copy link
Member

@StanFromIrelandStanFromIrelandFeb 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
returnf"{platform}≥{version}"
returnf"{platform}>={version}"

How well supported is "≥"? Does it render well in pdf outputs?

Copy link
Member

@StanFromIrelandStanFromIrelandFeb 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

epub
image

Copy link
ContributorAuthor

@m-aciekm-aciekFeb 3, 2025•
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@AA-Turner could you please advise, is there some direct way to recognize epub build in the directive code and fallback to >=? Or should I rather drop the UTF-8 character from here?

Copy link
Member

@hugovkhugovkFeb 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I find no mention of using "≥" or ">=" for versions in the Google, Microsoft and Apple style guides, and they say to use words such as "Use version 2.2 or later" and not "Use version 2.2 or higher":

Copy link
Member

@StanFromIrelandStanFromIrelandFeb 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with @hugovk . This again will require translation.

Copy link
Member

@StanFromIrelandStanFromIrelandFeb 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I will add that >= is currently used.

image

Copy link
ContributorAuthor

@m-aciekm-aciekFeb 3, 2025•
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I find Google's style guide contradictory 🤔

A release with the highest version number might not be the latest version. For example, if version 2.0 of an operating system receives a bug-fix update after version 3.0 has been released, then version 2.0.1 might be the latest version, even though its version number is lower than 3.0.

In this meaning we rather want to express "higher" than "later". And later they recommend higher in Android docs. I've filed a feedback to this section.

I agree that the written form may be easier to read than the symbolic one. Though ≥ seems to be inambiguous, contrary to “later”.

I will add that >= is currently used.

I wonder what should be the approach, if we decide to use "Linux 2.6.27 or later", should we rewrite also the availability directives content in .rsts? Or introduce a simplified "syntax", that will be rendered to "or later" from a ">=" specificator? That may be confusing to docs editors. (?)

Copy link
Member

@hugovkhugovkFeb 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we choose to use words, I'd rewrite the existing ">=" to avoid problems/confusion by automation changing things in unexpected ways.

Copy link
Member

@hugovkhugovkFeb 4, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We discussed this in this month's docs workgroup meeting: let's keep the directives compact; they're not prose, and use the single symbol. The Unicode symbol was introduced in 1993, hopefully it renders well on near anything. If there's an issue with Unicode in some of the backends (such as man pages), we should fix that.

(Minutes will appear at https://docs-community.readthedocs.io/en/latest/monthly-meeting/index.html in the near future.)



def setup(app: Sphinx) -> ExtensionMetadata:
app.add_directive("availability", Availability)

Expand Down
1 change: 1 addition & 0 deletions Doc/tools/templates/dummy.html
View file
Open in desktop
Original file line numberDiff line numberDiff line change
Expand Up@@ -10,6 +10,7 @@
In extensions/availability.py:

{% trans %}Availability{% endtrans %}
{% trans %}not{platform}{% endtrans %}

In extensions/c_annotations.py:

Expand Down
Loading