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 |
veox
changed the title
|
The I'll try to fix it silently, and rewrite the PR description. For the Unsquashed git history in this branch of mine. |
veox
force-pushed
the
use-yul-lexer-in-docs
branch
from
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!..
veox
force-pushed
the
use-yul-lexer-in-docs
branch
from
2142f5e
to
a481ea7
Compare
veox
changed the title
|
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-soliditydependency in docs, so Yul can be highlighted separately from Solidity.This changes all instances of
codetocode-blockinyul.rst, with explicit language specification;highlightis intentionally not used. See commit a481ea7 for reasoning.Closes #8608 as implemented.
Note:
codeis a generic reStructuredText's directive; and Sphinx promotescode-blockinstead; andcodeisn'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".