Make use of newer sphinxcontrib-programoutput2 extension (#1458)

The newer version of programoutput does render ANSI escapes from
our examples, making them easier to read.

Also swaps the codeclimate docs example with a smaller one, as we do
need to display a big file to demonstrate this functionality.

docs/conf.py

@@ -18,6 +18,8 @@
 import sys
 from pathlib import Path
 
+import pkg_resources
+
 # Make in-tree extension importable in non-tox setups/envs, like RTD.
 # Refs:
 # https://github.com/readthedocs/readthedocs.org/issues/6311
@@ -55,6 +57,18 @@
     'rules_table_generator_ext',  # in-tree extension
 ]
 
+
+# Fail safe protection to detect conflicting packages
+try:
+    pkg_resources.get_distribution("sphinxcontrib-programoutput")
+    print(
+        "FATAL: We detected presence of sphinxcontrib-programoutput package instead of sphinxcontrib-programoutput2 one. You must be sure the first is not installed.",
+        file=sys.stderr,
+    )
+    sys.exit(2)
+except pkg_resources.DistributionNotFound:
+    pass
+
 # Later on, add 'sphinx.ext.viewcode' to the list if you want to have
 # colorized code generated too for references.
 
@@ -251,8 +265,8 @@
 
 # table width fix via: https://rackerlabs.github.io/docs-rackspace/tools/rtd-tables.html
 html_static_path = ['_static']
-html_context = {
-    'css_files': [
-        '_static/theme_overrides.css',  # override wide tables in RTD theme
-    ],
-}
+
+html_css_files = [
+    'theme_overrides.css',  # override wide tables in RTD theme
+    'ansi.css',
+]

docs/requirements.in

@@ -3,4 +3,4 @@ myst-parser
 pipdeptree
 Sphinx
 sphinx_ansible_theme
-sphinxcontrib.programoutput
+sphinxcontrib-programoutput2>=2.0a1

docs/requirements.txt

@@ -27,27 +27,27 @@ myst-parser==0.13.5
 packaging==20.9
 pipdeptree==2.0.0
 pycparser==2.20
-pygments==2.8.0
+pygments==2.8.1
 pyparsing==2.4.7
 pytz==2021.1
 pyyaml==5.4.1
 requests==2.25.1
-rich==9.12.4
+rich==9.13.0
 snowballstemmer==2.1.0
 sphinx-ansible-theme==0.3.2
 sphinx-notfound-page==0.6
 sphinx-rtd-theme==0.5.1
-sphinx==3.5.1
+sphinx==3.5.2
 sphinxcontrib-applehelp==1.0.2
 sphinxcontrib-devhelp==1.0.2
 sphinxcontrib-htmlhelp==1.0.3
 sphinxcontrib-jsmath==1.0.1
+sphinxcontrib-programoutput2==2.0a1
 sphinxcontrib-qthelp==1.0.3
 sphinxcontrib-serializinghtml==1.1.4
-sphinxcontrib.programoutput==0.16
 typing-extensions==3.7.4.3
 urllib3==1.26.3
-wcmatch==8.1.1
+wcmatch==8.1.2
 
 # The following packages are considered to be unsafe in a requirements file:
 # pip

docs/usage.rst

@@ -75,10 +75,10 @@ When you call ansible-lint without arguments the tool will use its internal
 heuristics to determine file types.
 
 ``ansible-lint`` also accepts a list of **roles** or **playbooks** as
-arguments. The following command lints ``examples/play.yml`` and
+arguments. The following command lints ``examples/playbooks/play.yml`` and
 ``examples/roles/bobbins`` role:
 
-.. command-output:: ansible-lint -p examples/play.yml examples/roles/bobbins
+.. command-output:: ansible-lint -p examples/playbooks/play.yml examples/roles/bobbins
    :cwd: ..
    :returncode: 2
    :nostderr:
@@ -100,14 +100,14 @@ the following:
 If playbooks include other playbooks, or tasks, or handlers or roles, these
 are also handled:
 
-.. command-output:: ansible-lint --offline -p examples/playbooks/include.yml
+.. command-output:: ansible-lint --force-color --offline -p examples/playbooks/include.yml
    :cwd: ..
    :returncode: 2
    :nostderr:
 
 A codeclimate report in JSON format can be generated with ansible-lint.
 
-.. command-output:: ansible-lint -f codeclimate examples/playbooks/example.yml
+.. command-output:: ansible-lint -f codeclimate examples/playbooks/norole.yml
    :cwd: ..
    :returncode: 2
    :nostderr:

test-requirements.txt

@@ -17,17 +17,17 @@ iniconfig==1.1.1
 packaging==20.9
 pluggy==0.13.1
 py==1.10.0
-pygments==2.8.0
+pygments==2.8.1
 pyparsing==2.4.7
 pytest-cov==2.11.1
 pytest-forked==1.3.0
 pytest-xdist==2.2.1
 pytest==6.2.2
 pyyaml==5.4.1
-rich==9.12.4
+rich==9.13.0
 toml==0.10.2
 typing-extensions==3.7.4.3
-wcmatch==8.1.1
+wcmatch==8.1.2
 
 # The following packages are considered to be unsafe in a requirements file:
 # setuptools

tox.ini

@@ -51,11 +51,15 @@ passenv =
   PY_COLORS
   REQUESTS_CA_BUNDLE  # https proxies
   SSL_CERT_FILE  # https proxies
+  LANG
+  LC_ALL
+  LC_CTYPE
 # recreate = True
 setenv =
   COVERAGE_FILE = {env:COVERAGE_FILE:{toxworkdir}/.coverage.{envname}}
   PIP_DISABLE_PIP_VERSION_CHECK = 1
   PRE_COMMIT_COLOR = always
+  FORCE_COLOR = 1
 whitelist_externals =
   sh