-
Notifications
You must be signed in to change notification settings - Fork 4
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add accessible versions of 'sphinx' and 'native' styles #15
Comments
Thanks for looping me in @asmeurer! This project looks like a wonderful idea! Regarding Furo... The default color schemes that Furo uses are
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 That is typically used by most Sphinx documentation, since older versions of Sphinx would spew out a I'm pretty sure getting a more-accessible color scheme for PS: I see why "I'd write a shorter letter if I had more time" is a thing someone said. :) |
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 |
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? |
We can definitely add these other themes - and it absolutely makes sense to reduce maintenance burden or at least unify tooling and infrastructure
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 |
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). |
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). 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. |
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
The text was updated successfully, but these errors were encountered: