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!..
