Custom code-block colours

[jameshadfield]

The current JSON code-fences use an unfortunate green/red colour combo, which I'd like to change!

The colours are defined in pygments.css. Unsure of the best approach to extending this / overwriting these in nextstrain.css but if someone could provide the framework I'll happily change some colours 😄

An example:

[tsibley]

The supported way to do this with Sphinx and Pygment is to set the Sphinx option, pygments_style, controlling the Pygments style to use: either one of the builtin styles or a custom, plugin-provided style. A custom style would be part of this nextstrain-sphinx-theme package and registered as a Pygments plugins in our setup.py here.

The unsupported way would be to override the specific CSS used for highlighting in Sphinx's HTML output, e.g. something like:

.highlight-json .nt { color: purple } /* NT = Name.Tag = JSON object field */

Upside is we can restyle JSON highlighting without affecting other highlighted blocks that may contain Name.Tag tokens (produced by Pygments lexers).

Downsides are that this will break if the Pygments JSON lexer changes or the CSS generation changes, and it won't apply to non-HTML output. (Not sure if these get any use currently, though I believe RTD is producing them.) Other downside is we can't restyle whole families of lexed tokens, like the Name family, but only individual token types directly, like Name.Tag.

[jameshadfield]

Builtin styles! Yay! Now to choose one... I've always liked solarized-light and I think a (subtle) background colour for code blocks would be a good idea.

[jameshadfield]

Here's how nextstrain/docs.nextstrain.org#113 looks after adding pygments_style = 'solarized-light' to the docs.nextstrain.org config - much better in my opinion!

I attempted to add this to our theme (i.e. this repo) via changing

sphinx-theme/lib/nextstrain/sphinx/theme/theme.conf

Line 5 in eb4f16c

pygments_style = default

to 'solarized-light' but the rendered HTML test pages from this repo still used the default style. I couldn't actually find the docs on how to develop this theme locally -- I was using python3 -m pip install -e . and make html which I'm guessing isn't right?

[tsibley]

Hmm. I've always found Solarized Light to be a bit low contrast in many cases, e.g. as in here

I attempted to add this to our theme (i.e. this repo) via changing [theme.conf] to 'solarized-light' but the rendered HTML test pages from this repo still used the default style. I couldn't actually find the docs on how to develop this theme locally -- I was using python3 -m pip install -e . and make html which I'm guessing isn't right?

That's the right thing to do… and it works for me (see screenshot above). Maybe you need a make clean first? The change to theme.conf won't be picked up as a change to the build dependencies.

[tsibley]

Another example of where I think Solarized Light is low contrast and (de)emphasizes the wrong things: