Skip to content

Conversation

@dgw
Copy link
Member

@dgw dgw commented Aug 28, 2021

Description

In the dark color scheme particularly, the default Pygments style ("native") has some weird choices in places like imports (underlined names), and bland colors.

Having the styles selected explicitly in the docs' conf.py also means we aren't subject to surprise default-value changes from Furo.

Notes

I'm not dead set on these choices. They're just the best-looking to me, out of the options I tested (about 60-70% of the available styles) at https://pygments.org/demo/. Got a suggestion that looks better? I'm all eyes.

In particular, I'd love a more colorful style for light mode to match the choice I made in dark mode, but the light-mode styles that do use significant amounts of color are generally quite muted. The few that choose bolder colors come off as garish to me, or even unreadable (light cyan on white, for example—no thanks).

Checklist

  • I have read CONTRIBUTING.md
  • I can and do license this contribution under the EFLv2
  • No issues are reported by make qa (runs make quality and make test)
    • (No code changes.)
  • I have tested the functionality of the things this change touches
    • See comparisons below.

Comparisons

Light mode

sphinx vs. friendly

Dark mode

native vs. monokai

In the dark color scheme particularly, the default Pygments style
("native") has some weird choices in places like imports (underlined
names), and bland colors.

Having the styles selected explicitly in the docs' `conf.py` also means
we aren't subject to surprise default-value changes from Furo.
@dgw dgw added this to the 8.0.0 milestone Aug 28, 2021
@dgw dgw requested a review from a team August 28, 2021 05:20
@Exirel
Copy link
Contributor

Exirel commented Aug 28, 2021

If you want an opinion on that:

  • I slightly prefer the Sphinx default for light
  • I kind of like Monokai more than the default for dark

So I think it's pretty good.

@dgw
Copy link
Member Author

dgw commented Oct 20, 2021

I'm honestly just going to call this "an improvement" and leave any better ideas to separate patches. Most of us who read the docs on a regular basis already use the dark theme, I suspect, and that side of things is 👌 already with this change.

@dgw dgw merged commit d0b0356 into master Oct 20, 2021
@dgw dgw deleted the docs-pygments-style branch October 20, 2021 05:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants