Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Use Yul lexer in docs #8778

Merged
merged 1 commit into from
Apr 27, 2020
Merged

Use Yul lexer in docs #8778

merged 1 commit into from
Apr 27, 2020

Commits on Apr 26, 2020

  1. 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!..
    @veox
    veox committed Apr 26, 2020
    Configuration menu
    Copy the full SHA
    a481ea7 View commit details
    Browse the repository at this point in the history