-
Notifications
You must be signed in to change notification settings - Fork 5.7k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Use Yul lexer in docs #8778
Use Yul lexer in docs #8778
Conversation
Thanks! I was considering changing all the random uses of |
That would work, although I'm not sure that's the intended use. IDK really, no strong opinion. ... Or it might not, if |
Ah, That's a shame, it looked nice. Guess Argh! That didn't work:
Trying An alternative would be to build the docs in a |
The I'll try to fix it silently, and rewrite the PR description. For the Unsquashed git history in this branch of mine. |
4734adb
to
2142f5e
Compare
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!..
2142f5e
to
a481ea7
Compare
This ended up more difficult than expected; but is now otherwise "done". I'll poke CircleCI in a week for the Also, I'd now really advise against using |
I'll push this over to a branch in the Solidity repo to get a macos run |
Actually, b_osx is fully unrelated to this. |
Thanks a lot for your help! |
Update
pygments-lexer-solidity
dependency in docs, so Yul can be highlighted separately from Solidity.This changes all instances of
code
tocode-block
inyul.rst
, with explicit language specification;highlight
is intentionally not used. See commit a481ea7 for reasoning.Closes #8608 as implemented.
Note:
code
is a generic reStructuredText's directive; and Sphinx promotescode-block
instead; andcode
isn't even mentioned in Sphinx's docs - although it's included, and "works", but differently thancode-block
; quite confusing to dig through while figuring "why X isn't working".