docs: add CLI output with color to page

Signed-off-by: Henry Schreiner <henryfs@princeton.edu>

Author: henryiii

docs/conf.py

@@ -17,10 +17,12 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions  coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
+    "erbsland.sphinx.ansi",
     "sphinx.ext.autodoc",
     "sphinx.ext.doctest",
     "sphinx.ext.extlinks",
     "sphinx.ext.intersphinx",
+    "sphinxcontrib.programoutput",
 ]
 
 # General information about the project.
@@ -103,3 +105,14 @@
     "python": ("https://docs.python.org/3/", None),
     "pypug": ("https://packaging.python.org/", None),
 }
+
+
+# -- Options for programout ----------------------------------------------------------
+# https://sphinxcontrib-programoutput.readthedocs.io
+
+programoutput_use_ansi = True
+
+# Needed to ensure color output
+# See https://github.com/OpenNTI/sphinxcontrib-programoutput/issues/77
+os.environ["FORCE_COLOR"] = "1"
+os.environ.pop("NO_COLOR", None)

docs/version.rst

@@ -52,3 +52,17 @@ Reference
 .. automodule:: packaging.version
     :members:
     :special-members:
+
+
+CLI
+---
+
+A CLI utility is provided:
+
+.. program-output:: python -m packaging.version --help
+
+You can compare two versions:
+
+.. program-output:: python -m packaging.version compare --help
+
+.. versionadded:: 26.1

pyproject.toml

@@ -46,7 +46,10 @@ test = [
   "tomli_w",
 ]
 docs = [
+  "erbsland-sphinx-ansi; python_version>='3.10'",
   "furo",
+  "sphinx",
+  "sphinxcontrib-programoutput >=0.19",
   "typing-extensions>=4.1.0; python_version < '3.9'",
 ]
 benchmark = [