Add accessible versions of 'sphinx' and 'native' styles

[asmeurer]

For the SymPy docs we have been using accessible variants of the 'sphinx' and 'native' styles. See https://github.com/sympy/sympy/blob/master/doc/src/_pygments/styles.py. I would love to be able to offload the maintenances of these custom styles to this project (or ideally to upstream them to Sphinx/pygments, but that's a harder task).

Here is the script that I used to generate them https://gist.github.com/asmeurer/d78409ea033aeeb764a11bb4acaeccc2. It is unfortunately very hacky and relies on a Ruby tool, so if there is better tooling in this repo, that would be preferable. I didn't see in this repo what tooling was used to generate/test these themes to ensure they are WCAG AA compatible.

These styles are notable because they are the default styles for the Furo Sphinx theme. "sphinx" is also the default style used in many other Sphinx themes including the default one. CC @pradyunsg

[pradyunsg]

Thanks for looping me in @asmeurer! This project looks like a wonderful idea!

Regarding Furo...

The default color schemes that Furo uses are tango (light) and native (dark). These specific themes are used by Furo since... well...

1. They were the best-among-the-defaults themes, when I was looking, that didn't look out of place with rest of Furo's neutral backgrounds.
2. I didn't want to figure out how to write a pygments theme and bother adding yet-another-thing for me to maintain.

I'd happily eagerly adopt more accessible alternatives to those themes (they don't need to be equivalent even!) -- as long as the background color doesn't look out of place with Furo's neutral background colors. :)

Regarding the sphinx pygments theme...

That is typically used by most Sphinx documentation, since older versions of Sphinx would spew out a pygments_style = "sphinx" (or something like that) in their template generation. This has been removed in newer versions, falling back to theme defaults -- and multiple themes use sphinx as their default (as noted already!).

I'm pretty sure getting a more-accessible color scheme for sphinx upstreamed will be relatively straightforward -- although, it'll only be beneficial after a certain version of Sphinx, so having it be available via a third-party is still a very good idea.

PS: I see why "I'd write a shorter letter if I had more time" is a thing someone said. :)

[asmeurer]

Oh I didn't realize that the Furo default wasn't "sphinx", and it's only used because of the template generation. Sorry for misspeaking on that.

Just to be clear, "sphinx" itself is based on the "friendly" pygments style, with only a few small differences, most notably the yellow background, which messes with the color contrast of some of the friendly defaults. https://github.com/sphinx-doc/sphinx/blob/master/sphinx/pygments_styles.py

[steff456]

Hi guys! Thanks for opening this issue, I'll work in a first version for the variants scipy use and then we can iterate from there 😬. Do you have any preferred name for the themes?

[trallard]

We can definitely add these other themes - and it absolutely makes sense to reduce maintenance burden or at least unify tooling and infrastructure

(or ideally to upstream them to Sphinx/pygments, but that's a harder task).

This is definitely something I/we have talked about as well as discussed with other folks working on documentation infrastructure. Long-term I'd like to see this upstreamed, though that would require IMHO additional support infra to ensure later changes to the themes would not mess up the contrast and the such.

Thanks for your contribution & thoughts @asmeurer and @pradyunsg

[asmeurer]

though that would require IMHO additional support infra to ensure later changes to the themes would not mess up the contrast and the such.

I hadn't thought about that. Is there a Python library that can compute the WCAG contrast ratio between two web colors? I found https://pypi.org/project/wcag-contrast-ratio/, but I don't know how accurate or up-to-date it is (it was last updated in 2015).

Maybe it would be useful to have a small Python library that can compute the contrast ratios of a Pygments theme, and maybe even produce a high contrast alternative (similar to the Ruby tool I used to generate the above themes). Pygments may also be interested in having this upstream (or maybe it already exists).

[trallard]

yup - I have not found such a library, so we might need to engineer something like that. There are also a couple of formulas one can use to calculate the contrast ratio, which impacts the compliance results (because we like making our lives harder).
Initially, we could write a lightweight script or so to check only contrast ratios and WCAG compliance during CI or the such as a good MVP.

Still doing some research on how to go about it and what other colour contrast checkers use for this, so stay tuned.

My main worry right now when pushing / upstreaming accessibility changes to libraries and the such is how I can not only make this contribution but also help the maintainers or at least not overburden them, considering that not all folks are accessibility experts and the whole accessibility tooling, standards, practices, etc. are pretty complex. So I am "maybe" too cautious and prefer to think about the solution + maintainability from the get-go.