Colorize Sphinx output

[webknjaz]

Some CIs don't expose enough information for tools to decide whether they support ANSI-sequences while it's experimentally proven that they do. TBH most of the existing envs support this. In such cases, we need to explicitly tell the tools to output the color markers.
For Sphinx, this essentially means adding --color when invoking it. I think this should be a part of the skeleton.

[jaraco]

Can you explain more? Looking at the docs, I see -N for disabling color but nothing for enabling color. Is --color an undocumented feature that forces color for when support fails to be autodetected?

[webknjaz]

Yes. It looks like the docs web page doesn't mention it, but running --help has it documented:

$ python -m sphinx --help 
[...]
  --color           do emit colored output (default: auto-detect)
  -N, --no-color    do not emit colored output (default: auto-detect)
[...]

[jaraco]

According to docs, the FORCE_COLOR env var should do the trick.

Unfortunately, that doesn't seem to be the case (see this recent run):

There's color in there, but it's implicit color ("warning" text signals red on the line). Based on what I see on my mac, if sphinx color were honored, one should see bold text and purple/green for "index".

Since the current configuration is already configured correctly to support color, I'm disinclined to add additional configuration, at least without an upstream report explaining why the existing FORCE_COLOR is insufficient. A redundant config would be cruft.

I'm declaring this done and welcome further investigation to determine why FORCE_COLOR is not honored.

[webknjaz]

IIRC Sphinx itself honors the environment variable but the underlying library does not. Also, custom extensions may end up not honoring it too..

[webknjaz]

@jaraco also, shouldn't there be a passenv in tox.ini for this to work? Oh, it's passed through an env var I forgot..

[webknjaz]

Found that PR I was trying to remember. It seemed to be colorama's fault: tartley/colorama#230.

Though when I dag deeper, it turned out Sphinx only uses it under Windows.