search

python / python-docs-theme

Sphinx theme for Python documentation
Other
74 stars 58 forks source link

Underline links for readability and a11y #160

Closed hugovk closed 8 months ago

hugovk commented 10 months ago

Currently this theme changes the colour of hyperlinks but doesn't underline them.

For example: https://docs.python.org/3/whatsnew/3.12.html

image

When hovering over a link, it changes colour and a link is shown (see "f-strings" here):

image

However, links should always be underlined. This improves accessibility and also readability.

For example:

Not using underlines also fails a WCAG check:

And GitHub have just enabled underlines:

Demo

https://python-docs-theme-previews--160.org.readthedocs.build/en/160/whatsnew/3.12.html

image image
ncoghlan commented 10 months ago

@hugovk I was about to hit merge on this, but then I wondered: Should we tag it for backport to the active maintenance branches as well?

Personally, I'm not seeing a downside to doing that, and a whole lot of benefits.

hugovk commented 10 months ago

Yes, using this on the active maintenance branches is good.

Note we're in the https://github.com/python/python-docs-theme repo, not https://github.com/python/cpython. We'll release this theme to PyPI, and then it'll be used by the backport branches the next time they rebuild:

ezio-melotti commented 10 months ago

I find the screenshot with underlines "noisier" than the current one, and I suspect the underlines were not added to the docs' theme in the first place for similar reasons. Wikipedia also doesn't have underlines and cites possible confusion when a link contains underscores (it might have a setting to still enable underlines though).

Given that both our docs and Wikipedia are rich in links, and that -- especially for our docs -- there are often underscores in the text of the links, do the guidelines that suggest adding underlines still apply?

For reference, here are a couple of examples of underlined links that contain underscores: image image

Perhaps the contrast could be tweaked instead, or a lighter/different (e.g. dotted) underline could be used instead? Another solution could be to do like GitHub did and add them as an option, but that requires more work.

hugovk commented 10 months ago

Good point, let's consider narrowing/lowering the underline, and see how GitHub and MDN do it.

hugovk commented 9 months ago

Updated to make the underline thinner, move it down a bit, and also increase the line height so it better fits in the gap.

"Line height (line spacing) to at least 1.5 times the font size" is also one of the WCAG 2.1 guidelines, and improves accessibility through readability.

https://www.w3.org/WAI/WCAG21/Understanding/text-spacing.html

Here's how the earlier snippets with underscores look:

image image

And from What's New in 3.13:

image

And from What's New in 3.12:

image

How does this look?

ezio-melotti commented 9 months ago

This is definitely better and solves the potential confusion with underscores. I'm now -0 (from -1) on this since I still prefer the version without underlines, but if others prefer the underlines I'm fine with the change.

egeakman commented 6 months ago

Hi there @hugovk. Is there Discourse discussion for this? I believe there should be a discussion first. I would like to hear people's opinions.

hugovk commented 6 months ago

There wasn't a discussion for this, just this PR that was open for two months before merge, and one month before release.

This was prompted by GitHub recently adding underlines for accessibility. In addition to approvals here, core devs were in support (on Discord), and some said underlines help with poor eyesight or colourblindness.

Some references: