search

flux-framework / flux-docs

Documentation for the Flux-Framework
https://flux-framework.readthedocs.io/
Other
12 stars 21 forks source link

Admin Guide: syntax highlighting in TOML examples #64

Closed SteVwonder closed 4 years ago

SteVwonder commented 4 years ago

It looks like the admin guide uses TOML code blocks in the ReST code, and the syntax highlighting of those blocks works on GitHub but not on ReadTheDocs. Not sure if this reproduces locally, but it happens on the hosted RTD site.

GitHub Screenshot:

Screen Shot 2020-09-16 at 12 38 44 PM

RTD Screenshot:

Screen Shot 2020-09-16 at 12 38 52 PM
SteVwonder commented 4 years ago

It seems to work just fine locally, so maybe it is a versioning or dependency issue with the hosted version that RTD is running:

Screen Shot 2020-09-16 at 12 48 09 PM

Locally I'm running Sphinx v3.2.1.

grondo commented 4 years ago

Yeah, worked locally for me as well. (Sphinx 3.1.2)

SteVwonder commented 4 years ago

After recreating the virtualenv that RTD uses on my local machine, it looks to be due to an older version of Pygments:

Running Sphinx v1.8.5
Initializing Spelling Checker
loading pickled environment... failed: unsupported pickle protocol: 5
loading intersphinx inventory from https://flux-framework.readthedocs.io/projects/flux-rfc/en/latest/objects.inv...
loading intersphinx inventory from https://flux-framework.readthedocs.io/projects/flux-core/en/latest/objects.inv...
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 8 source files that are out of date
updating environment: 8 added, 0 changed, 0 removed
reading sources... [100%] quickstart
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] quickstart
/Users/herbein1/Repositories/flux-framework/flux-docs/adminguide.rst:139: WARNING: Pygments lexer name u'toml' is not known
/Users/herbein1/Repositories/flux-framework/flux-docs/adminguide.rst:150: WARNING: Pygments lexer name u'toml' is not known
/Users/herbein1/Repositories/flux-framework/flux-docs/adminguide.rst:169: WARNING: Pygments lexer name u'toml' is not known
/Users/herbein1/Repositories/flux-framework/flux-docs/adminguide.rst:184: WARNING: Pygments lexer name u'toml' is not known
/Users/herbein1/Repositories/flux-framework/flux-docs/adminguide.rst:207: WARNING: Pygments lexer name u'toml' is not known
/Users/herbein1/Repositories/flux-framework/flux-docs/adminguide.rst:244: WARNING: Pygments lexer name u'toml' is not known
generating indices... genindex
writing additional pages... search
copying static files... done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded, 6 warnings.

If we bump the python version in the RTD config file, then we will be able to pull in a newer version of Pygments for the hosted build. I'll give that a shot with a quick PR now.

grondo commented 4 years ago

Nice! Thanks for looking into this (I would have had no idea where to start)

SteVwonder commented 4 years ago

Np! After doing all that local reproduction, I realized you can just click on individual commands run within the RTD build and the output gets expanded out, like in Travis (but not as obvious a UI as Travis): https://readthedocs.org/projects/flux-framework/builds/11897212/