Docs: enable translations of code blocks

[m-aciek]

Documentation

Code blocks, e.g. in the tutorial, include comments that are complement to the regular content of tutorial articles. An example in tutorial's introduction in section “Numbers”:

>>> 17 / 3  # classic division returns a float
5.666666666666667
>>>
>>> 17 // 3  # floor division discards the fractional part
5
>>> 17 % 3  # the % operator returns the remainder of the division
2
>>> 5 * 3 + 2  # floored quotient * divisor + remainder
17

I'd like to propose changing gettext builder configuration by allowing 'literal-block' element types translation.

The topic previously was brought up on doc-sig mailing list without a conclusion.

Linked PRs

• gh-123407: Docs: enable translations of code blocks #123408
• [3.13] gh-123407: Enable translating literal and code blocks (GH-123408) #123530
• [3.12] gh-123407: Enable translating literal and code blocks (GH-123408) #123531
• gh-123407: Allow translation of doctest blocks content #123852

[zware]

Makes sense to me. Would you like to submit a PR?

[m-aciek]

Sure! Here it is: #123408.

[JulienPalard]

Damned, I just noticed that, it broke the po syntax checker, the orthograph checker, the grammar checker, and sphinx-lint in python-docs-fr CI :D I'll have to find a way to disable it :D

[m-aciek]

Sorry for that! Please see my comment in sphinx-lint.

[rffontenelle]

@JulienPalard My workaround for this issue is basically disabling 'literal-block', generating POT, updating PO, running all desired checkers, and then undoing this change in po files. Obviously, this workaround cannot be run before committing the changes.

In shell script, this means something like:

cd cpython/Doc
# comment (removing would work too)
sed -i "/^\s*'literal-block',/s/ '/ #'/" conf.py
# generate new po template files
make gettext
# update PO files from POT
sphinx-intl update --locale-dir path/to/pofiles --pot-dir build/gettext
# run the desired checkers
# finally, undo the changes
git -C path/to/pofiles checkout .

p.s.: make gettext is available as of Python 3.12.