Color of fonts used in code

[colonelcoleslaw@…]

I've appreciated the thorough documentation, but can barely read much of the code samples on the light-green background. It's really bad.

[Aymeric Augustin]

I'll defer to someone who feels qualified to decide if the contrast is indeed too low.

[Idan Gazit]

Documentation with the existing code block coloring

[Idan Gazit]

Documentation with a monochrome code block background

[Idan Gazit]

I'm not a huge fan of the green background for code samples, however I don't think it qualifies as "barely legible." I'm loath to touch something that has worked fine for many people, or at least, has failed to elicit comment from them.

That being said, I've attached two screenshots, one depicting the current state of affairs, and one with a grey-background for code blocks.

I'd like to see a docs style refactor in a future django, might as well think about this aspect now.

Opinions welcome!

[Idan Gazit]

Apologies, unclear "next step":

I'll leave this open to comment for a month. Absent engaged discussion, I'll make some decision on Dec 1st or the 1.4 deadline, whichever comes first.

[shaunkelly]

It's more the text colors than the background color that makes it harder to read, particularly the comment/keyword grey, and the light blue and yellow. In fact the grey is probably less readable on a grey background. I attached a quick mockup replacing those colors with more saturated versions for a little more contrast.

Though, besides the comments, I wouldn't classify it as barely legible either.

[Claude Paroz]

Interesting resources:

• ​http://www.w3.org/TR/WCAG/
• ​http://snook.ca/technical/colour_contrast/colour.html

I tested for example the color values of brown text on green background. It fails miserably :-(

[jimallman <jim@…>]

An easy alternative is to adjust the background color used for code samples. A tint used over large areas doesn't need to be so dark/intense.

In this case, #F3FFE5 works pretty well in my opinion, and comments and keywords don't disappear.

[Idan Gazit]

I feel like this is a bikeshed, and the actual problem is not so grave. None of the existing solutions (mine included) is a significant improvement over the original, and I'd rather see some thought applied towards revamping the sphinx theme of the docs—a part of which will be giving some love to the styling of code blocks in the context of the new style.

Thanks all for your thoughts, I've bookmarked this ticket for when that day comes. If you'd like to see this move forward, the next step is a concrete proposal which outlines the larger problems with / potential improvements to the existing docs. It doesn't need to offer solutions, but it does need to scope out the issues we should tackle.