gh-135828: Disable syntax highlighting in Using Python on macOS#150074
Open
Taeknology wants to merge 1 commit into
Open
gh-135828: Disable syntax highlighting in Using Python on macOS#150074Taeknology wants to merge 1 commit into
Taeknology wants to merge 1 commit into
Conversation
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
Doc/using/mac.rsthas no top-level.. highlight::directive, sothe project default from
Doc/conf.py(highlight_language = 'python3')is applied. The page only contains
parsed-literalblocks for shellsnippets — these need
parsed-literalso that|version|substitutionswork (added in #130400). With the
python3lexer active, Pygmentschokes 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_failurewarnings, and thetranslated page even renders the shell snippets with syntax highlighting
plus red error rectangles around
$.Fix
Add
.. highlight:: noneat the top ofDoc/using/mac.rst, matchingthe pattern already used by
Doc/using/windows.rstandDoc/using/editors.rst. This prevents thepython3lexer from beingapplied to the
parsed-literalblocks while keeping the|version|substitutions intact.
Verification
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:English HTML output is unchanged. Built
Doc/using/mac.htmlfrom
upstream/main(baseline) and from this branch, then diffed:The only difference is the build timestamp. Body content is
identical, so existing English readers see exactly the same page.
Builds succeed. Both baseline and the fix produce
build succeeded, 1 warning.The single warning is the well-knownpartial-build search index notice ("색인이 불완전합니다") emitted
when building a single file, and is unrelated to this change.
Pattern parity with sibling files. The directive matches what
Doc/using/windows.rst:1andDoc/using/editors.rst:1already do.Reproducing the original translation-side warning requires a translated
build (e.g. the
python-docs-pt-brrepository), but the root cause isthe
python3lexer being applied to shell text — items (1) and (4)remove that cause directly, so the symptom cannot recur regardless of
language.