🧪 Start linting YAML/JSON code blocks in docs

This uses a third-party Sphinx extension now [[1]]. In the future,
though, we should explore using the solution from
ansible-documentation [[2]].

[1]: https://github.com/kai687/sphinxawesome-codelinter
[2]: ansible/ansible-documentation#2385

Author: webknjaz

.github/workflows/ci-cd.yml

@@ -515,6 +515,7 @@ jobs:
         - pre-commit
         - metadata-validation
         - build-docs
+        - codelinter-docs
         - coverage-docs
         - doctest-docs
         - linkcheck-docs

.github/workflows/pip-tools.yml

@@ -87,6 +87,7 @@ jobs:
         lock-file-env:
         - build-dists
         - build-docs
+        - codelinter-docs
         - coverage-docs
         - doctest-docs
         - linkcheck-docs
@@ -106,6 +107,8 @@ jobs:
           lock-file-extra-input: pyproject.toml
         - lock-file-env: build-docs
           lock-file-extra-input: ''
+        - lock-file-env: codelinter-docs
+          lock-file-extra-input: ''
         - lock-file-env: coverage-docs
           lock-file-extra-input: ''
         - lock-file-env: doctest-docs

dependencies/direct/build-docs.in

@@ -6,4 +6,6 @@ Sphinx  # main docs framework
 sphinx-autodoc-typehints  # gets function param types from annotations
 sphinx-issues  # Sphinx roles providing support for linking GitHub
 sphinx-tabs  # Sphinx directives providing support for HTML tabs
+sphinxawesome-codelinter  # lints snippets of embedded code
 sphinxcontrib-apidoc  # automatic API pages generator
+yamllint  # called by `sphinxawesome-codelinter`

dependencies/direct/codelinter-docs.in

@@ -0,0 +1 @@
+build-docs.in

docs/conf.py

@@ -76,6 +76,7 @@
     'sphinx_autodoc_typehints',  # gets function param types from annotations
     'sphinx_issues',  # implements `:issue:`, `:pr:` and other GH-related roles
     'sphinx_tabs.tabs',
+    'sphinxawesome.codelinter',  # checks code blocks with linters
     'sphinxcontrib.apidoc',
 
     # In-tree extensions:
@@ -135,6 +136,13 @@
 typehints_use_signature = True
 typehints_use_signature_return = True
 
+# -- Options for sphinxawesome.codelinter extension --------------------------
+
+codelinter_languages = {
+    'json': 'python -Im json.tool',
+    'yaml': 'python -Im yamllint -',
+}
+
 # -- Options for sphinxcontrib.apidoc extension ------------------------------
 
 apidoc_excluded_paths = []

tox.ini

@@ -398,6 +398,40 @@ pass_env =
   READTHEDOCS*  # Present @ RTD
 
 
+[testenv:codelinter-docs]
+allowlist_externals =
+  {[testenv:build-docs]allowlist_externals}
+description = Lint code snippets in docs
+changedir = {[testenv:build-docs]changedir}
+commands_pre =
+  # Retrieve possibly missing commits:
+  -git fetch --unshallow
+  -git fetch --tags
+
+  # Clean up sphinxcontrib-apidoc generated RST files:
+  -git clean -x -f -- 'pkg{/}*.rst'
+commands =
+  {envpython} \
+    {[python-cli-options]byte-errors} \
+    {[python-cli-options]max-isolation} \
+    {[python-cli-options]warnings-to-errors} \
+    -m sphinx \
+      -j auto \
+      {tty:--color} \
+      -a \
+      -n \
+      -W --keep-going \
+      -b codelinter \
+      -d '{temp_dir}{/}.doctrees' \
+      . \
+      {posargs:{envtmpdir}{/}codelinter}
+commands_post =
+deps =
+  -r{toxinidir}{/}dependencies{/}direct{/}{envname}.in
+pass_env =
+  {[testenv:build-docs]pass_env}
+
+
 [testenv:coverage-docs]
 allowlist_externals =
   {[testenv:build-docs]allowlist_externals}