Improving readability of documentation tables #311
Description
Activity
- changed the title [-]Improving readability of documentation[/-] [+]Improving readability of documentation tables[/+] on May 17, 2026
I am not convinced that this would be better. This particlar listing is not really a table. I would change
The following table lists operations available for [set](https://docs.python.org/3/library/stdtypes.html#set) that do not apply to immutable instances of [frozenset](https://docs.python.org/3/library/stdtypes.html#frozenset):
to
The following [set](https://docs.python.org/3/library/stdtypes.html#set) operations do not apply to immutable instances of [frozenset](https://docs.python.org/3/library/stdtypes.html#frozenset):
Reacted by Petr ViktorinIts not really about it being a table or not, its that alternating background colors makes it easier to read.
The biggest trouble with your illustration is the background colour changes between related operations, which is harder to read. It might be more palatable with set.update, set |= other, and the description all one shade, then set.intersection_update, set &= other, and its description a different shade, etc.
Reacted by Stan UlbrychIt was just a quick example, you could customise it more if you wanted to.
I think this feature proposal needs discussion on https://discuss.python.org/c/documentation/26 and should be closed until there is consensus.
Documentation
I was reading through the documentation and I thought of a way you could make it read better.
You could do the thing thats done with tables where you alternate the background color to make the elements easier to distinguish at a glance.
I made a quick example using inspect element to color every other method in the documentation.
vs what it looks like currently.
My quick test was done by adding
And replacing the margin on the dl elements with padding so the background color would fill it.
I originally used dl:nth-child(odd) but .py.method:nth-child(odd) worked better, but it would probably be better to add a new class to the elements you want highlight instead, because dl:nth-child(odd) highlights too much and .py.method:nth-child(odd) doesnt highlight all of the elements you would probably want highlighted.
Should work but adding a new class is probably easier to maintain and you could reuse it in more places.