Repository navigation
Improving readability of documentation tables #311
Description
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
.py.method:nth-child(odd) {
background-color: #2d2d2d;
}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.
*:is(.py.method, .describe):nth-child(odd of *:is(.py.method, .describe)) {
background-color: #2b2b2b;
}Should work but adding a new class is probably easier to maintain and you could reuse it in more places.
Activity
[-]Improving readability of documentation[/-][+]Improving readability of documentation tables[/+]terryjreedy commentedon May 17, 2026
I am not convinced that this would be better. This particlar listing is not really a table. I would change
to
Vwert commentedon May 17, 2026
Its not really about it being a table or not, its that alternating background colors makes it easier to read.
vadmium commentedon May 17, 2026
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.
Vwert commentedon May 17, 2026
It was just a quick example, you could customise it more if you wanted to.
terryjreedy commentedon May 22, 2026
I think this feature proposal needs discussion on https://discuss.python.org/c/documentation/26 and should be closed until there is consensus.