Unable to translate parsed-literal block from using/mac.rst

Documentation

Two literal blocks from using/mac.rst's Installing using the command line section preceded by a parsed-literal directive can't be translated without having the Sphinx build triggering:

Lexing literal_block '<the whole block text in here>' as "python3" resulted in an error at token: '$'. Retrying in relaxed mode. [misc.highlighting_failure]

See this python-docs-pt-br's CI run for an example.

If I leave the translation empty or simply copy-and-paste the original string, this issue doesn't happen. Any other translation fails. For instance, translating a comment line like "download installer pkg" to "baixa o pkg do instalar" will fail.

Also, I noticed that the translated documentation has syntax highlight (colors and everthing) and a red rectangle around the $ signs, while the original documentation has no syntax highlight at all.

See screenshots taken just now of the published Brazilian Portuguese translation and the original:

Linked PRs

@picnixz

Well I think its more like a Sphinx issue. CC @picnixz

This seems related to this old Sphinx issue: sphinx-doc/sphinx#2167

But from the diff I can find no concrete reason why, except possibly not escaping \\ |version|\\ :

"# download installer pkg\n"                                                                       |    "# baixa o pkg instalador\n"
"curl -O \\https://www.python.org/ftp/python/\\ |version|\\ .0/${RELEASE}\n"                            "curl -O \\https://www.python.org/ftp/python/\\ |version|\\ .0/${RELEASE}\n"
"\n"                                                                                                    "\n"
"# create installer choicechanges to customize the install:\n"                                     |    "# cria choicechanges instalador para personalizar a instalação:\n"
"#    enable the PythonTFramework-\\ |version|\\  package\n"                                       |    "#    habilita o pacote PythonTFramework-\\ |version|\n"
"#    while accepting the other defaults (install all other packages)\n"                           |    "#    enquanto aceita outros padrões (instala todos os outros pacotes)\n"

I propose we remove all parsed literals, they seem to not add anything and there are only a few:

Doc/license.rst:.. parsed-literal::
Doc/license.rst:.. parsed-literal::
Doc/license.rst:.. parsed-literal::
Doc/license.rst:.. parsed-literal::
Doc/license.rst:.. parsed-literal::
Doc/using/mac.rst:    .. parsed-literal::
Doc/using/mac.rst:  .. parsed-literal::
Doc/using/mac.rst:  .. parsed-literal::
Doc/using/mac.rst:  .. parsed-literal::
Doc/using/mac.rst:  .. parsed-literal::
Doc/using/mac.rst:.. parsed-literal::
Doc/using/mac.rst:.. parsed-literal::

FWIW, the use of parsed-literal was recently added to Doc/using/mac.rst replacing code-block's. The discussion of why this was done is in #130400.

PR #150074 proposes a fix for this issue and has been awaiting review since May. All checks are passing. Could someone take a look when available?

gh-135828: Disable syntax highlighting in Using Python on macOS (#150074

[3.14] gh-135828: Disable syntax highlighting in Using Python on macOS (

[3.13] gh-135828: Disable syntax highlighting in Using Python on macOS (

[3.15] gh-135828: Disable syntax highlighting in Using Python on macOS (

pythongh-135828: Disable syntax highlighting in Using Python on macOS (…

Navigation Menu

Repository navigation

Unable to translate parsed-literal block from using/mac.rst #135828

Documentation

Linked PRs

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Unable to translate parsed-literal block from using/mac.rst #135828

Description

Documentation

Linked PRs

Activity

LamentXU123 commented on Jun 23, 2025

StanFromIreland commented on Jun 23, 2025

ned-deily commented on Jun 26, 2025

Taeknology commented on Jul 29, 2026

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions