The HTML design feels outdated as it uses older HTML styling. I suggest to refresh the design at least by means of partial modernization. It’s especially visible when you visit devguide subdomain and compare it to docs. Some of these things can be considered taste preference, while others are representing legitimate concern. A few suggestions provided below:
Make design more responsive
With wider screens, `devguide` definitely renders much nicer
Remove list style type (or at least add option to make lists without type/use that option in many places)
Add tooltips at least for the glossary and basic terms
Add more themes, make font customizable, improve accessibility
Add labels for the select input elements in the top bar to improve accessibility
Redesign side bar
Remove vertical bars from the tables
Remove excessive important! properties from the css.
P.S. I was unable to provide images for illustration because of the forum’s limitation on embedded media posting for new users…
Full unformatted version with illustrations
1. Make design more responsive
[details=With wider screens, `devguide` definitely renders much nicer]
[/details]
2. Add more spacing to top bar: it is too dense
[details]
I will compare it to Github's one since `devguide` doesn't have a topbar
[/details]
3. Remove list style type (or at least add option to make lists without type/use that option in many places)
[details]
Before:
After:
[/details]
4. Add tooltips at least for the glossary and basic terms
5. Add more themes, make font customizable, improve accessibility
6. Add labels for the `select` input elements in the top bar to improve [accessibility](https://dequeuniversity.com/rules/axe/4.8/select-name)
7. Redesign side bar
8. Remove vertical bars from the tables
[details]
Example-1:
to
Example-2:
to
[/details]
9. Remove excessive `important!` properties from the css.
Hi Kerim, I bumped your account up a trust level so you should be able to post your images and links, or edit your posts above to contain them.
As to your points, the docs theme is certainly quite old and creaky as far as it comes to HTML styling. The docs team has been notionally strongly considering a migration to highly modern theme like @pradyunsg 's Lutra, under development with large documentation sets like CPython’s specifically in mind, as well as work by @hugovk and others to modernize low-hanging fruit in the current theme (dark mode, a11y, etc) where feasible.
I’m sure we’d welcome your contributions along these lines to both of those efforts, after due consideration and discussion of any major changes that might warrant broader feedback.
Do you mean using <abbr>? It has limited and inconsistent support for keyboard users, touch users (e.g. mobile) and for screenreader and Braille users:
I’m not sure if we should have multiple themes, or if Sphinx even supports it. It would mean we need to maintain integration of 2x or 3x or more themes (plus light+dark).
If we can let people customise the font via browser settings, that would probably be best.
Do you mean using ? It has limited and inconsistent support for keyboard users, touch users (e.g. mobile) and for screenreader and Braille users:
I meant more like wikipedia-style tooltips so users recap information quickly, it might help in studying. We can add “title” attritbute to <a> tags and display it with JS from cached json with dictionary.
I’m not sure if we should have multiple themes, or if Sphinx even supports it. It would mean we need to maintain integration of 2x or 3x or more themes (plus light+dark).
I was thinking more of “light” themes which would rather mostly be a color schemes, like obsidian, monokai etc.
I bumped your account up a trust level so you should be able to post your images and links
Thanks
Also thank you for providing an accurate depiction of the current situation along with links, hopefully I can make meaningful contribution for both of these efforts. It would make sense to start with minor improvements and move to another theme for bigger things (e.g. top/side-bar redesign).
