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

Enable FORCE_COLOR and NO_COLOR for terminal colouring

4 files changed, 22 insertions, 0 deletions

diff --git a/AUTHORS b/AUTHORS
index 4b6aa8ffb..492817cfb 100644
--- a/AUTHORS
+++ b/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
diff --git a/CHANGES b/CHANGES
index a7c913c9c..ab3b86d3a 100644
--- a/CHANGES
+++ b/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
diff --git a/doc/man/sphinx-build.rst b/doc/man/sphinx-build.rst
index ca16b265a..9bba4a55a 100644
--- a/doc/man/sphinx-build.rst
+++ b/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
diff --git a/sphinx/util/console.py b/sphinx/util/console.py
index cc22390a5..abdbf4219 100644
--- a/sphinx/util/console.py
+++ b/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():