PEP 1, 12: Update to reflect guidance for correct syntax highlighting #2445
Conversation
This file contains 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
CAM-Gerlach
added
lint
CAM-Gerlach
requested review from
brettcannon,
warsaw and
ncoghlan
as code owners
CAM-Gerlach
requested review from
hugovk and
JelleZijlstra
and removed request for
warsaw and
ncoghlan
JelleZijlstra
approved these changes
Mar 19, 2022
hugovk
approved these changes
Mar 19, 2022
CAM-Gerlach
commented
Mar 19, 2022
|
|
||
| Random J. User <[email protected]> | ||
| .. code-block:: text |
There was a problem hiding this comment.
NB, I would have just added .. highlight:: text to the top of the PEP, but unlike the other languages (e.g. .. highlight:: rst in PEP 12), it doesn't change the highlight lexer of literal blocks without an explicit text language from default to text (which I can see comparing the DOM with and without it on this PEP vs. PEP 12), and results in this block still getting highlighted (incorrectly). Not sure if its a Sphinx (or Pygments) bug or an expected behavior I'm not understanding, but either way it seems to be due to a special case with the text (i.e. no highlighting) "language"/Pygments lexer.
brettcannon
approved these changes
Mar 23, 2022
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.
Presently, PEP 12 doesn't mention how to ensure that the automatic syntax highlighting added in the new Sphinx/PEP 676 build system gives the intended rendered output. Therefore, this PR adds a passage to the Literal Blocks section mentioning when and how to do this for specific blocks or entire PEPs. In the process, it also updates and simplifies the existing text.
Additionally, it updates PEP 1 and PEP 12 to follow those practices themselves, so they render as intended and serve as a good example for PEP authors. A future PR will fix the other existing PEPs where the default
pythonsyntax highlighting is not giving the rendered result the original author intended, to proactively solve existing issues like #2430 ; in most cases, it can be accomplished merely by adding a single.. highlight:: languageto the top of the PEP.