Commit Graph

9 Commits

Author SHA1 Message Date
Kamil Śliwak
0aeb1ef47e Require sphinx-rtd-theme>= 0.5.2; older 2021-07-14 13:50:03 +02:00
Kamil Śliwak
98c4830f2a docs/requirements.txt: Add minimum version for Sphinx 2021-06-21 20:54:35 +02:00
Alex Beregszaszi
522fdc158d Update pygments-lexer-solidity to 0.7.0 2021-03-25 20:29:05 +00:00
Daniel Kirchner
bd21535dd1 Rewrite of the antlr grammar. 2020-08-19 17:55:31 +02:00
Noel Maersk
a481ea719f
docs: use Yul lexer to highlight Yul code segments.
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!..
2020-04-26 20:48:07 +03:00
Noel Maersk
ad975a6f8c docs: bump Solidity lexer package to v0.3.1.
That release includes stricter matching of "nested" globals, i.e.
it highlights `msg.sender` but not `sender`.
2018-05-24 14:58:30 +03:00
Noel Maersk
4004fa8c98 docs: bump required Solidity lexer package version.
pygments-lexer-solidity 0.3.0 highlights NatSpec specials like
@author, @title, etc..
2018-05-24 14:18:07 +03:00
Noel Maersk
7acf5d5244 docs: use SolidityLexer from pygments_lexer_solidity package. 2018-05-23 16:56:51 +03:00
chriseth
20d67c0fce Add requirements.txt for readthedocs. 2018-05-14 22:17:27 +02:00