Merge pull request #10260 from hugovk/colour-env-vars

Enable FORCE_COLOR and NO_COLOR for terminal colouring

Author: tk0miya

AUTHORS

@@ -73,6 +73,7 @@ Other contributors, listed alphabetically, are:
 * Pauli Virtanen -- autodoc improvements, autosummary extension
 * Eric N. Vander Weele -- autodoc improvements
 * Stefan van der Walt -- autosummary extension
+* Hugo van Kemenade -- support FORCE_COLOR and NO_COLOR
 * Thomas Waldmann -- apidoc module fixes
 * John Waltman -- Texinfo builder
 * Barry Warsaw -- setup command improvements

CHANGES

@@ -15,6 +15,7 @@ Deprecated
 Features added
 --------------
 
+* #10260: Enable ``FORCE_COLOR`` and ``NO_COLOR`` for terminal colouring
 * #10234: autosummary: Add "autosummary" CSS class to summary tables
 * #10125: extlinks: Improve suggestion message for a reference having title
 * #9494, #9456: html search: Add a config variable

doc/man/sphinx-build.rst

@@ -304,6 +304,22 @@ variables to customize behavior:
    Additional options for :program:`sphinx-build`. These options can
    also be set via the shortcut variable **O** (capital 'o').
 
+.. describe:: NO_COLOR
+
+   When set (regardless of value), :program:`sphinx-build`  will not use color
+   in terminal output. ``NO_COLOR`` takes precedence over ``FORCE_COLOR``. See
+   `no-color.org <https://no-color.org/>`__ for other libraries supporting this
+   community standard.
+
+   .. versionadded:: 4.5.0
+
+.. describe:: FORCE_COLOR
+
+   When set (regardless of value), :program:`sphinx-build` will use color in
+   terminal output. ``NO_COLOR`` takes precedence over ``FORCE_COLOR``.
+
+   .. versionadded:: 4.5.0
+
 .. _when-deprecation-warnings-are-displayed:
 
 Deprecation Warnings

sphinx/util/console.py

@@ -49,9 +49,13 @@ def term_width_line(text: str) -> str:
 
 
 def color_terminal() -> bool:
+    if 'NO_COLOR' in os.environ:
+        return False
     if sys.platform == 'win32' and colorama is not None:
         colorama.init()
         return True
+    if 'FORCE_COLOR' in os.environ:
+        return True
     if not hasattr(sys.stdout, 'isatty'):
         return False
     if not sys.stdout.isatty():