docs: use Yul lexer to highlight Yul code segments. #8782
Closed
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
Many commits squashed; turns out that with the combination of:
* Python v2.7,
* Sphinx v1.8.5, and
* Pygments v2.3.1
versions (old!) used in the CI, the only viable approach is:
* to use `code-block` directives with explicit language specification,
* to provide no file-local default using `highlight`, and
* to set language as `none` for grammar specifications.
Underlying are the following issues (again, for the old versions
listed above):
* Generic RST `code` doesn't work when language is `none`:
Warning, treated as error:
/root/project/docs/yul.rst:430:Cannot analyze code. No Pygments lexer found for "none".
Additionally, it might be trying to fall back to the default
(Solidity) if left unspecified.
* If a file-local default is specified using `highlight`, then
`code-block` _must_ also provide a language:
Warning, treated as error:
/root/project/docs/yul.rst:185:Error in "code-block" directive:
1 argument(s) required, 0 supplied.
* Sphinx seems to try the file-local default "yul" (specified with
`highlight`) on `code` marked having language `json`:
Warning, treated as error:
/root/project/docs/yul.rst:130:Could not lex literal_block as "yul". Highlighting skipped.
* The only well-lexed highlighter for two of the three grammar
specifications is `peg`, but it was added in Pygments v2.6.
One of the grammars - in the "Formal Specification" section,
the one after "We will use a destructuring notation for the
AST nodes." - _must_ be left unhighlighted, with language set
to `none`: all lexers do really poorly.
... And one should never, ever start treating warnings as mere
warnings, without having exhausted all other options.
Otherwise, it's a slippery slope, - and look where that brought
Gandhi: to being a strawman in every lousy argument to be had!..
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.
Replaces #8778
Closes #8608