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

[Taeknology]

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

Problem

Doc/using/mac.rst has no top-level .. highlight:: directive, so
the project default from Doc/conf.py (highlight_language = 'python3')
is applied. The page only contains parsed-literal blocks for shell
snippets — these need parsed-literal so that |version| substitutions
work (added in #130400). With the python3 lexer active, Pygments
chokes on tokens like $ in the shell examples.

In English builds Pygments silently retries in relaxed mode, so nothing
visible breaks. In translated builds (e.g.
python-docs-pt-br)
the failure surfaces as misc.highlighting_failure warnings, and the
translated page even renders the shell snippets with syntax highlighting
plus red error rectangles around $.

Fix

Add .. highlight:: none at the top of Doc/using/mac.rst, matching
the pattern already used by Doc/using/windows.rst and
Doc/using/editors.rst. This prevents the python3 lexer from being
applied to the parsed-literal blocks while keeping the |version|
substitutions intact.

Verification

1. Pygments python3 lexer fails on $ (root cause confirmed).
   Running the lexer directly on a representative shell snippet from
   the page yields three Token.Error '$' tokens:

   $ ./venv/bin/python -c "from pygments.lexers import get_lexer_by_name; ..."
   python3 lexer error tokens count: 3
     Token.Error '$'
     Token.Error '$'
     Token.Error '$'
   

2. English HTML output is unchanged. Built Doc/using/mac.html
   from upstream/main (baseline) and from this branch, then diffed:

   $ diff Doc/_build/baseline_html/using/mac.html \
          Doc/_build/html/using/mac.html
   746c746
   <       Last updated on May 19, 2026 (10:38 UTC).
   ---
   >       Last updated on May 19, 2026 (10:32 UTC).
   

   The only difference is the build timestamp. Body content is
   identical, so existing English readers see exactly the same page.

3. Builds succeed. Both baseline and the fix produce
   build succeeded, 1 warning. The single warning is the well-known
   partial-build search index notice ("색인이 불완전합니다") emitted
   when building a single file, and is unrelated to this change.

4. Pattern parity with sibling files. The directive matches what
   Doc/using/windows.rst:1 and Doc/using/editors.rst:1 already do.

Reproducing the original translation-side warning requires a translated
build (e.g. the python-docs-pt-br repository), but the root cause is
the python3 lexer being applied to shell text — items (1) and (4)
remove that cause directly, so the symptom cannot recur regardless of
language.

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

[hugovk]

Thanks, this seems like a reasonable fix.

If we ever want to apply highlighting on this page, we can move . highlight:: none just before .. parsed-literal:: and reset like .. highlight:: python3 afterwards.

@picnixz I guess the longer-term fix is for Sphinx not to apply highlighting to parsed-literal?

[hugovk]

Looks like sphinx-doc/sphinx#12287 is the upstream Sphinx bug, and sphinx-doc/sphinx#12238 is a stalled PR to fix it.

[miss-islington-app]

Thanks @Taeknology for the PR, and @hugovk for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13, 3.14, 3.15.
🐍🍒⛏🤖

[bedevere-app]

GH-154958 is a backport of this pull request to the 3.15 branch.

[bedevere-app]

GH-154959 is a backport of this pull request to the 3.14 branch.

[bedevere-app]

GH-154960 is a backport of this pull request to the 3.13 branch.