Opened 2 years ago

Closed 2 years ago

#17089 closed Cleanup/optimization (wontfix)

Color of fonts used in code

Reported by: colonelcoleslaw@… Owned by: nobody
Component: Documentation Version: 1.3
Severity: Normal Keywords:
Cc: Triage Stage: Someday/Maybe
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: yes


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

Attachments (3)

code_original.png (146.4 KB) - added by idangazit 2 years ago.
Documentation with the existing code block coloring
code_grey.png (142.3 KB) - added by idangazit 2 years ago.
Documentation with a monochrome code block background
contrasty_text.png (68.3 KB) - added by shaunkelly 2 years ago.

Download all attachments as: .zip

Change History (11)

comment:1 Changed 2 years ago by aaugustin

  • Component changed from Uncategorized to Web site
  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Triage Stage changed from Unreviewed to Design decision needed
  • Type changed from Uncategorized to Cleanup/optimization
  • UI/UX set

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

Last edited 2 years ago by aaugustin (previous) (diff)

Changed 2 years ago by idangazit

Documentation with the existing code block coloring

Changed 2 years ago by idangazit

Documentation with a monochrome code block background

comment:2 Changed 2 years ago by idangazit

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!

comment:3 Changed 2 years ago by idangazit

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.

comment:4 Changed 2 years ago by idangazit

  • Component changed from Web site to Documentation

Changed 2 years ago by shaunkelly

comment:5 Changed 2 years ago by 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.

comment:6 Changed 2 years ago by claudep

Interesting resources:

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

comment:7 Changed 2 years ago by 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.

comment:8 Changed 2 years ago by idangazit

  • Resolution set to wontfix
  • Status changed from new to closed
  • Triage Stage changed from Design decision needed to Someday/Maybe

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.

Add Comment

Modify Ticket

Change Properties
<Author field>
as closed
as The resolution will be set. Next status will be 'closed'
The resolution will be deleted. Next status will be 'new'

E-mail address and user name can be saved in the Preferences.

Note: See TracTickets for help on using tickets.