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!..
Specify white space for table cells
Add custom.css for docs to change pre tag styles
Specify white space for table cells
Rearrange code
Delete theme_overrides.css
Remove extra code
RTD probably has their `default` theme set to their own `rtd` theme,
while CircleCI has some regular default Sphinx theme.
This changes the Sphinx project configuration to use `rtd` as the
theme.
