Skip to content

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

Open
Taeknology wants to merge 1 commit into
python:mainfrom
Taeknology:gh-135828-mac-rst-highlight-none
Open

gh-135828: Disable syntax highlighting in Using Python on macOS#150074
Taeknology wants to merge 1 commit into
python:mainfrom
Taeknology:gh-135828-mac-rst-highlight-none

Conversation

@Taeknology
Copy link
Copy Markdown

@Taeknology Taeknology commented May 19, 2026

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.

The page uses parsed-literal blocks for shell snippets so that
`|version|` substitutions work. Without an explicit highlight
language, Sphinx applies the project default (`python3`), which
makes the Pygments python3 lexer choke on tokens like `$` in the
shell examples. The English build silently retries in relaxed mode,
but translated builds (e.g. python-docs-pt-br) surface this as
`misc.highlighting_failure` warnings and add an unwanted highlight
to the rendered output.

Add `.. highlight:: none` at the top of the file, matching the
pattern already used by `Doc/using/windows.rst` and
`Doc/using/editors.rst`. The English HTML output is unchanged
(the page already rendered without highlight thanks to the lexer
fallback) and the translation builds no longer produce the warning.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

awaiting review docs Documentation in the Doc dir skip news

Projects

Status: Todo

Development

Successfully merging this pull request may close these issues.

1 participant