build: use cog --check-fail-msg to instruct devs

Author: nedbat

doc/cog_helpers.py

@@ -82,7 +82,11 @@ def show_configs(ini, toml):
     toml, toml_vals = _read_config(toml, "covrc.toml")
     for key, val in ini_vals.items():
         if val != toml_vals[key]:
-            cog.error(f"Mismatch! {key}:\nini:  {val!r}\ntoml: {toml_vals[key]!r}")
+            cog.error(
+                f"Mismatch between configuration tabs in docs for {key = }:\n"
+                + f"  ini:  {val!r}\n"
+                + f"  toml: {toml_vals[key]!r}"
+            )
 
     ini2 = re.sub(r"(?m)^\[", "[coverage:", ini)
     print()

tox.ini

@@ -81,8 +81,8 @@ deps =
 allowlist_externals =
     make
 commands =
-    # If this command fails, see the comment at the top of doc/cmd.rst
-    python -m cogapp -cP --check --verbosity=1 doc/*.rst
+    # If cog fails, it means the docs need to be updated. Run `make prebuild`.
+    python -m cogapp -cP --check --check-fail-msg='run `make prebuild`' --verbosity=1 doc/*.rst doc/*/*.rst
     doc8 -q --ignore-path 'doc/_*' doc CHANGES.rst README.rst
     sphinx-lint doc CHANGES.rst README.rst
     sphinx-build -b html -aEnqW doc doc/_build/html
@@ -102,9 +102,10 @@ setenv =
 
 commands =
     python -m tabnanny {env:LINTABLE}
-    # If this command fails, see the comment at the top of doc/cmd.rst
-    python -m cogapp -cP --check --verbosity=1 doc/*.rst
-    python -m cogapp -cP --check --verbosity=1 .github/workflows/*.yml
+    # If cog fails, it means the docs need to be updated. Run `make prebuild`.
+    python -m cogapp -cP --check --check-fail-msg='run `make prebuild`' --verbosity=1 doc/*.rst doc/*/*.rst
+    # If cog fails, it means the workflow files need to be updated. Run `make workflows`.
+    python -m cogapp -cP --check --check-fail-msg='run `make workflows`' --verbosity=1 .github/workflows/*.yml
     ruff format --check
     python -m pylint -j 0 --notes= --ignore-paths 'doc/_build/.*' {env:LINTABLE}
     check-manifest --ignore 'doc/sample_html/*'