search

nextstrain / sphinx-theme

A Sphinx theme for Nextstrain's documentation, based on Read The Docs' default theme.
https://docs.nextstrain.org/projects/sphinx-theme/
MIT License
0 stars 5 forks source link

Custom code-block colours #33

Open jameshadfield opened 1 year ago

jameshadfield commented 1 year ago

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: image

tsibley commented 1 year ago

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 commented 1 year ago

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 commented 1 year ago

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

image

I attempted to add this to our theme (i.e. this repo) via changing https://github.com/nextstrain/sphinx-theme/blob/eb4f16c77c99992808bf45a36ebbe1abfa6d61bf/lib/nextstrain/sphinx/theme/theme.conf#L5 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 commented 1 year ago

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

Screenshot from 2022-10-12 09-48-50

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 commented 1 year ago

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

image