mirror of
https://github.com/ethereum/solidity
synced 2023-10-03 13:03:40 +00:00
a481ea719f
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!..
|
||
|---|---|---|
| .. | ||
| _static | ||
| _templates | ||
| contracts | ||
| examples | ||
| internals | ||
| types | ||
| 050-breaking-changes.rst | ||
| 060-breaking-changes.rst | ||
| abi-spec.rst | ||
| assembly.rst | ||
| bugs_by_version.json | ||
| bugs.json | ||
| bugs.rst | ||
| cheatsheet.rst | ||
| common-patterns.rst | ||
| conf.py | ||
| contracts.rst | ||
| contributing.rst | ||
| control-structures.rst | ||
| grammar.rst | ||
| index.rst | ||
| installing-solidity.rst | ||
| introduction-to-smart-contracts.rst | ||
| layout-of-source-files.rst | ||
| logo.svg | ||
| make.bat | ||
| Makefile | ||
| metadata.rst | ||
| natspec-format.rst | ||
| requirements.txt | ||
| resources.rst | ||
| security-considerations.rst | ||
| solidity-by-example.rst | ||
| Solidity.g4 | ||
| structure-of-a-contract.rst | ||
| style-guide.rst | ||
| types.rst | ||
| units-and-global-variables.rst | ||
| using-the-compiler.rst | ||
| yul.rst | ||
