build: use cog to maintain data copied into docs

22 files changed, 323 insertions, 440 deletions

diff --git a/.github/workflows/kit.yml b/.github/workflows/kit.yml
index 3aa67dde..bed90069 100644
--- a/.github/workflows/kit.yml
+++ b/.github/workflows/kit.yml
@@ -39,7 +39,7 @@ jobs:
           # To change the matrix, edit the choices, then process this file with cog:
           #
           # $ python -m pip install cogapp
-          # $ python -m cogapp -rP .github/workflows/kit.yml
+          # $ python -m cogapp -crP .github/workflows/kit.yml
           #
           #
           # [[[cog
@@ -94,7 +94,7 @@ jobs:
           - {"os": "windows", "py": "cp39", "arch": "AMD64"}
           - {"os": "windows", "py": "cp310", "arch": "x86"}
           - {"os": "windows", "py": "cp310", "arch": "AMD64"}
-        # [[[end]]]
+        # [[[end]]] (checksum: dfc37c84db46011e5654945563c5ce68)
       fail-fast: false
 
     steps:
diff --git a/Makefile b/Makefile
index 681e6bf1..0032a3dd 100644
--- a/Makefile
+++ b/Makefile
@@ -118,24 +118,8 @@ WEBSAMPLEBETA = $(WEBHOME)/files/sample_coverage_html_beta
 $(DOCBIN):
 	tox -q -e doc --notest
 
-cmd_help: $(DOCBIN)
-	@for cmd in annotate combine debug erase html json report run xml; do \
-		echo > doc/help/$$cmd.rst; \
-		echo ".. This file is auto-generated by \"make dochtml\", don't edit it manually." >> doc/help/$$cmd.rst; \
-		echo >> doc/help/$$cmd.rst; \
-		echo ".. code::" >> doc/help/$$cmd.rst; \
-		echo >> doc/help/$$cmd.rst; \
-		echo "    $$ coverage $$cmd --help" >> doc/help/$$cmd.rst; \
-		$(DOCBIN)/python -m coverage $$cmd --help | \
-		sed \
-			-e 's/__main__.py/coverage/' \
-			-e '/^Full doc/d' \
-			-e 's/^./    &/' \
-			>> doc/help/$$cmd.rst; \
-	done
-
-dochtml: $(DOCBIN) cmd_help		## Build the docs HTML output.
-	$(DOCBIN)/python doc/check_copied_from.py doc/*.rst
+dochtml: $(DOCBIN) 			## Build the docs HTML output.
+	$(DOCBIN)/python -m cogapp -crP --verbosity=1 doc/*.rst
 	$(SPHINXBUILD) -b html doc doc/_build/html
 
 docdev: dochtml				## Build docs, and auto-watch for changes.
diff --git a/doc/check_copied_from.py b/doc/check_copied_from.py
deleted file mode 100644
index 79ec005b..00000000
--- a/doc/check_copied_from.py
+++ /dev/null
@@ -1,113 +0,0 @@
-# Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
-# For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
-
-"""Find lines in files that should be faithful copies, and check that they are.
-
-Inside a comment-marked section, any chunk of indented lines should be
-faithfully copied from FILENAME.  The indented lines are dedented before
-comparing.
-
-The section is between these comments:
-
-    .. copied_from <FILENAME>
-
-    .. end_copied_from
-
-This tool will print any mismatches, and then exit with a count of mismatches.
-
-"""
-
-import glob
-from itertools import groupby
-from operator import itemgetter
-import re
-import sys
-import textwrap
-
-
-def check_copied_from(rst_name):
-    """Check copies in a .rst file.
-
-    Prints problems.  Returns count of bad copies.
-    """
-    bad_copies = 0
-    file_read = None
-    file_text = None
-    with open(rst_name) as frst:
-        for filename, first_line, text in find_copied_chunks(frst):
-            if filename != file_read:
-                with open(filename) as f:
-                    file_text = f.read()
-                file_read = filename
-            if text not in file_text:
-                print("{}:{}: Bad copy from {}, starting with {!r}".format(
-                    rst_name, first_line, filename, text.splitlines()[0]
-                ))
-                bad_copies += 1
-
-    return bad_copies
-
-
-def find_copied_chunks(frst):
-    """Find chunks of text that are meant to be faithful copies.
-
-    `frst` is an iterable of strings, the .rst text.
-
-    Yields (source_filename, first_line, text) tuples.
-    """
-    for (_, filename), chunks in groupby(find_copied_lines(frst), itemgetter(0)):
-        chunks = list(chunks)
-        first_line = chunks[0][1]
-        text = textwrap.dedent("\n".join(map(itemgetter(2), chunks)))
-        yield filename, first_line, text
-
-
-def find_copied_lines(frst):
-    """Find lines of text that are meant to be faithful copies.
-
-    `frst` is an iterable of strings, the .rst text.
-
-    Yields tuples ((chunk_num, file_name), line_num, line).
-
-    `chunk_num` is an integer that is different for each distinct (blank
-    line separated) chunk of text, but has no meaning other than that.
-
-    `file_name` is the file the chunk should be copied from.  `line_num`
-    is the line number in the .rst file, and `line` is the text of the line.
-
-    """
-    in_section = False
-    source_file = None
-    chunk_num = 0
-
-    for line_num, line in enumerate(frst, start=1):
-        line = line.rstrip()
-        if in_section:
-            m = re.search(r"^.. end_copied_from", line)
-            if m:
-                in_section = False
-            else:
-                if re.search(r"^\s+\S", line):
-                    # Indented line
-                    yield (chunk_num, source_file), line_num, line
-                elif not line.strip():
-                    # Blank line
-                    chunk_num += 1
-        else:
-            m = re.search(r"^.. copied_from: (.*)", line)
-            if m:
-                in_section = True
-                source_file = m.group(1)
-
-
-def main(args):
-    """Check all the files in `args`, return count of bad copies."""
-    bad_copies = 0
-    for arg in args:
-        for fname in glob.glob(arg):
-            bad_copies += check_copied_from(fname)
-    return bad_copies
-
-
-if __name__ == "__main__":
-    sys.exit(main(sys.argv[1:]))
diff --git a/doc/cmd.rst b/doc/cmd.rst
index 189205ef..8c37781f 100644
--- a/doc/cmd.rst
+++ b/doc/cmd.rst
@@ -1,6 +1,27 @@
 .. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
 .. For details: https://github.com/nedbat/coveragepy/blob/master/NOTICE.txt
 
+.. [[[cog
+    import contextlib
+    import io
+    import re
+    import textwrap
+    from coverage.cmdline import CoverageScript
+
+    def show_help(cmd):
+        with contextlib.redirect_stdout(io.StringIO()) as stdout:
+            CoverageScript().command_line([cmd, "--help"])
+        help = stdout.getvalue()
+        help = help.replace("__main__.py", "coverage")
+        help = re.sub(r"(?m)^Full doc.*$", "", help)
+        help = help.rstrip()
+
+        print(".. code::\n")
+        print(f"    $ coverage {cmd} --help")
+        print(textwrap.indent(help, "    "))
+.. ]]]
+.. [[[end]]] (checksum: d41d8cd98f00b204e9800998ecf8427e)
+
 .. _cmd:
 
 ==================
@@ -90,7 +111,48 @@ Python ``-m`` switch::
 
 There are many options:
 
-.. include:: help/run.rst
+.. [[[cog show_help("run") ]]]
+.. code::
+
+    $ coverage run --help
+    Usage: coverage run [options] <pyfile> [program options]
+
+    Run a Python program, measuring code execution.
+
+    Options:
+      -a, --append          Append coverage data to .coverage, otherwise it starts
+                            clean each time.
+      --branch              Measure branch coverage in addition to statement
+                            coverage.
+      --concurrency=LIB     Properly measure code using a concurrency library.
+                            Valid values are: thread, gevent, greenlet, eventlet,
+                            multiprocessing.
+      --context=LABEL       The context label to record for this coverage run.
+      --include=PAT1,PAT2,...
+                            Include only files whose paths match one of these
+                            patterns. Accepts shell-style wildcards, which must be
+                            quoted.
+      -m, --module          <pyfile> is an importable Python module, not a script
+                            path, to be run as 'python -m' would run it.
+      --omit=PAT1,PAT2,...  Omit files whose paths match one of these patterns.
+                            Accepts shell-style wildcards, which must be quoted.
+      -L, --pylib           Measure coverage even inside the Python installed
+                            library, which isn't done by default.
+      -p, --parallel-mode   Append the machine name, process id and random number
+                            to the .coverage data file name to simplify collecting
+                            data from many processes.
+      --source=SRC1,SRC2,...
+                            A list of directories or importable names of code to
+                            measure.
+      --timid               Use a simpler but slower trace method. Try this if you
+                            get seemingly impossible results!
+      --debug=OPTS          Debug options, separated by commas. [env:
+                            COVERAGE_DEBUG]
+      -h, --help            Get help on this command.
+      --rcfile=RCFILE       Specify configuration file. By default '.coveragerc',
+                            'setup.cfg', 'tox.ini', and 'pyproject.toml' are
+                            tried. [env: COVERAGE_RCFILE]
+.. [[[end]]] (checksum: 869a31153b3cf401c52523ae9b52c7ab)
 
 If you want :ref:`branch coverage <branch>` measurement, use the ``--branch``
 flag.  Otherwise only statement coverage is measured.
@@ -302,7 +364,29 @@ indicating the file and the problem.
 The original input data files are deleted once they've been combined. If you
 want to keep those files, use the ``--keep`` command-line option.
 
-.. include:: help/combine.rst
+.. [[[cog show_help("combine") ]]]
+.. code::
+
+    $ coverage combine --help
+    Usage: coverage combine [options] <path1> <path2> ... <pathN>
+
+    Combine data from multiple coverage files collected with 'run -p'.  The
+    combined results are written to a single file representing the union of the
+    data. The positional arguments are data files or directories containing data
+    files. If no paths are provided, data files in the default data file's
+    directory are combined.
+
+    Options:
+      -a, --append     Append coverage data to .coverage, otherwise it starts
+                       clean each time.
+      --keep           Keep original coverage files, otherwise they are deleted.
+      -q, --quiet      Don't print messages about what is happening.
+      --debug=OPTS     Debug options, separated by commas. [env: COVERAGE_DEBUG]
+      -h, --help       Get help on this command.
+      --rcfile=RCFILE  Specify configuration file. By default '.coveragerc',
+                       'setup.cfg', 'tox.ini', and 'pyproject.toml' are tried.
+                       [env: COVERAGE_RCFILE]
+.. [[[end]]] (checksum: ddd34bbd27ab1fda8dabce80e4d67795)
 
 
 .. _cmd_erase:
@@ -312,7 +396,21 @@ Erase data: ``coverage erase``
 
 To erase the collected data, use the **erase** command:
 
-.. include:: help/erase.rst
+.. [[[cog show_help("erase") ]]]
+.. code::
+
+    $ coverage erase --help
+    Usage: coverage erase [options]
+
+    Erase previously collected coverage data.
+
+    Options:
+      --debug=OPTS     Debug options, separated by commas. [env: COVERAGE_DEBUG]
+      -h, --help       Get help on this command.
+      --rcfile=RCFILE  Specify configuration file. By default '.coveragerc',
+                       'setup.cfg', 'tox.ini', and 'pyproject.toml' are tried.
+                       [env: COVERAGE_RCFILE]
+.. [[[end]]] (checksum: 27f64e800a037c7e8f90289affdd5f13)
 
 If your configuration file indicates parallel data collection, **erase** will
 remove all of the data files.
@@ -366,7 +464,44 @@ For each module executed, the report shows the count of executable statements,
 the number of those statements missed, and the resulting coverage, expressed
 as a percentage.
 
-.. include:: help/report.rst
+.. [[[cog show_help("report") ]]]
+.. code::
+
+    $ coverage report --help
+    Usage: coverage report [options] [modules]
+
+    Report coverage statistics on modules.
+
+    Options:
+      --contexts=REGEX1,REGEX2,...
+                            Only display data from lines covered in the given
+                            contexts. Accepts Python regexes, which must be
+                            quoted.
+      --fail-under=MIN      Exit with a status of 2 if the total coverage is less
+                            than MIN.
+      -i, --ignore-errors   Ignore errors while reading source files.
+      --include=PAT1,PAT2,...
+                            Include only files whose paths match one of these
+                            patterns. Accepts shell-style wildcards, which must be
+                            quoted.
+      --omit=PAT1,PAT2,...  Omit files whose paths match one of these patterns.
+                            Accepts shell-style wildcards, which must be quoted.
+      --precision=N         Number of digits after the decimal point to display
+                            for reported coverage percentages.
+      --sort=COLUMN         Sort the report by the named column: name, stmts,
+                            miss, branch, brpart, or cover. Default is name.
+      -m, --show-missing    Show line numbers of statements in each module that
+                            weren't executed.
+      --skip-covered        Skip files with 100% coverage.
+      --no-skip-covered     Disable --skip-covered.
+      --skip-empty          Skip files with no code.
+      --debug=OPTS          Debug options, separated by commas. [env:
+                            COVERAGE_DEBUG]
+      -h, --help            Get help on this command.
+      --rcfile=RCFILE       Specify configuration file. By default '.coveragerc',
+                            'setup.cfg', 'tox.ini', and 'pyproject.toml' are
+                            tried. [env: COVERAGE_RCFILE]
+.. [[[end]]] (checksum: e5e77534929d2579f9d022227ef97313)
 
 The ``-m`` flag also shows the line numbers of missing statements::
 
@@ -441,7 +576,46 @@ the highlighting.
 A number of keyboard shortcuts are available for navigating the report.
 Click the keyboard icon in the upper right to see the complete list.
 
-.. include:: help/html.rst
+.. [[[cog show_help("html") ]]]
+.. code::
+
+    $ coverage html --help
+    Usage: coverage html [options] [modules]
+
+    Create an HTML report of the coverage of the files.  Each file gets its own
+    page, with the source decorated to show executed, excluded, and missed lines.
+
+    Options:
+      --contexts=REGEX1,REGEX2,...
+                            Only display data from lines covered in the given
+                            contexts. Accepts Python regexes, which must be
+                            quoted.
+      -d DIR, --directory=DIR
+                            Write the output files to DIR.
+      --fail-under=MIN      Exit with a status of 2 if the total coverage is less
+                            than MIN.
+      -i, --ignore-errors   Ignore errors while reading source files.
+      --include=PAT1,PAT2,...
+                            Include only files whose paths match one of these
+                            patterns. Accepts shell-style wildcards, which must be
+                            quoted.
+      --omit=PAT1,PAT2,...  Omit files whose paths match one of these patterns.
+                            Accepts shell-style wildcards, which must be quoted.
+      --precision=N         Number of digits after the decimal point to display
+                            for reported coverage percentages.
+      -q, --quiet           Don't print messages about what is happening.
+      --show-contexts       Show contexts for covered lines.
+      --skip-covered        Skip files with 100% coverage.
+      --no-skip-covered     Disable --skip-covered.
+      --skip-empty          Skip files with no code.
+      --title=TITLE         A text string to use as the title on the HTML.
+      --debug=OPTS          Debug options, separated by commas. [env:
+                            COVERAGE_DEBUG]
+      -h, --help            Get help on this command.
+      --rcfile=RCFILE       Specify configuration file. By default '.coveragerc',
+                            'setup.cfg', 'tox.ini', and 'pyproject.toml' are
+                            tried. [env: COVERAGE_RCFILE]
+.. [[[end]]] (checksum: 75eda57d99b6c7b736f8ab2d60cc765d)
 
 The title of the report can be set with the ``title`` setting in the
 ``[html]`` section of the configuration file, or the ``--title`` switch on
@@ -485,7 +659,35 @@ compatible with `Cobertura`_.
 
 .. _Cobertura: http://cobertura.github.io/cobertura/
 
-.. include:: help/xml.rst
+.. [[[cog show_help("xml") ]]]
+.. code::
+
+    $ coverage xml --help
+    Usage: coverage xml [options] [modules]
+
+    Generate an XML report of coverage results.
+
+    Options:
+      --fail-under=MIN      Exit with a status of 2 if the total coverage is less
+                            than MIN.
+      -i, --ignore-errors   Ignore errors while reading source files.
+      --include=PAT1,PAT2,...
+                            Include only files whose paths match one of these
+                            patterns. Accepts shell-style wildcards, which must be
+                            quoted.
+      --omit=PAT1,PAT2,...  Omit files whose paths match one of these patterns.
+                            Accepts shell-style wildcards, which must be quoted.
+      -o OUTFILE            Write the XML report to this file. Defaults to
+                            'coverage.xml'
+      -q, --quiet           Don't print messages about what is happening.
+      --skip-empty          Skip files with no code.
+      --debug=OPTS          Debug options, separated by commas. [env:
+                            COVERAGE_DEBUG]
+      -h, --help            Get help on this command.
+      --rcfile=RCFILE       Specify configuration file. By default '.coveragerc',
+                            'setup.cfg', 'tox.ini', and 'pyproject.toml' are
+                            tried. [env: COVERAGE_RCFILE]
+.. [[[end]]] (checksum: 7f5bcdcacbd60e32514201f24c56c17f)
 
 You can specify the name of the output file with the ``-o`` switch.
 
@@ -537,7 +739,40 @@ JSON reporting: ``coverage json``
 
 The **json** command writes coverage data to a "coverage.json" file.
 
-.. include:: help/json.rst
+.. [[[cog show_help("json") ]]]
+.. code::
+
+    $ coverage json --help
+    Usage: coverage json [options] [modules]
+
+    Generate a JSON report of coverage results.
+
+    Options:
+      --contexts=REGEX1,REGEX2,...
+                            Only display data from lines covered in the given
+                            contexts. Accepts Python regexes, which must be
+                            quoted.
+      --fail-under=MIN      Exit with a status of 2 if the total coverage is less
+                            than MIN.
+      -i, --ignore-errors   Ignore errors while reading source files.
+      --include=PAT1,PAT2,...
+                            Include only files whose paths match one of these
+                            patterns. Accepts shell-style wildcards, which must be
+                            quoted.
+      --omit=PAT1,PAT2,...  Omit files whose paths match one of these patterns.
+                            Accepts shell-style wildcards, which must be quoted.
+      -o OUTFILE            Write the JSON report to this file. Defaults to
+                            'coverage.json'
+      --pretty-print        Format the JSON for human readers.
+      -q, --quiet           Don't print messages about what is happening.
+      --show-contexts       Show contexts for covered lines.
+      --debug=OPTS          Debug options, separated by commas. [env:
+                            COVERAGE_DEBUG]
+      -h, --help            Get help on this command.
+      --rcfile=RCFILE       Specify configuration file. By default '.coveragerc',
+                            'setup.cfg', 'tox.ini', and 'pyproject.toml' are
+                            tried. [env: COVERAGE_RCFILE]
+.. [[[end]]] (checksum: 6fbe1ca09a8f0379a5e1794d8ac14e79)
 
 You can specify the name of the output file with the ``-o`` switch.  The JSON
 can be nicely formatted by specifying the ``--pretty-print`` switch.
@@ -580,7 +815,32 @@ For example::
     >     else:
     >         a = 2
 
-.. include:: help/annotate.rst
+.. [[[cog show_help("annotate") ]]]
+.. code::
+
+    $ coverage annotate --help
+    Usage: coverage annotate [options] [modules]
+
+    Make annotated copies of the given files, marking statements that are executed
+    with > and statements that are missed with !.
+
+    Options:
+      -d DIR, --directory=DIR
+                            Write the output files to DIR.
+      -i, --ignore-errors   Ignore errors while reading source files.
+      --include=PAT1,PAT2,...
+                            Include only files whose paths match one of these
+                            patterns. Accepts shell-style wildcards, which must be
+                            quoted.
+      --omit=PAT1,PAT2,...  Omit files whose paths match one of these patterns.
+                            Accepts shell-style wildcards, which must be quoted.
+      --debug=OPTS          Debug options, separated by commas. [env:
+                            COVERAGE_DEBUG]
+      -h, --help            Get help on this command.
+      --rcfile=RCFILE       Specify configuration file. By default '.coveragerc',
+                            'setup.cfg', 'tox.ini', and 'pyproject.toml' are
+                            tried. [env: COVERAGE_RCFILE]
+.. [[[end]]] (checksum: 8c3175a256f38215016d03b66de23d5b)
 
 Other common reporting options are described above in :ref:`cmd_reporting`.
 
@@ -603,7 +863,24 @@ Three types of information are available:
 * ``data``: show a summary of the collected coverage data
 * ``premain``: show the call stack invoking coverage
 
-.. include:: help/debug.rst
+.. [[[cog show_help("debug") ]]]
+.. code::
+
+    $ coverage debug --help
+    Usage: coverage debug <topic>
+
+    Display information about the internals of coverage.py, for diagnosing
+    problems. Topics are: 'data' to show a summary of the collected data; 'sys' to
+    show installation information; 'config' to show the configuration; 'premain'
+    to show what is calling coverage.
+
+    Options:
+      --debug=OPTS     Debug options, separated by commas. [env: COVERAGE_DEBUG]
+      -h, --help       Get help on this command.
+      --rcfile=RCFILE  Specify configuration file. By default '.coveragerc',
+                       'setup.cfg', 'tox.ini', and 'pyproject.toml' are tried.
+                       [env: COVERAGE_RCFILE]
+.. [[[end]]] (checksum: 66c36bb462796800400d588fa5a71c5f)
 
 .. _cmd_run_debug:
 
diff --git a/doc/dbschema.rst b/doc/dbschema.rst
index 42cf26cc..c6f3395e 100644
--- a/doc/dbschema.rst
+++ b/doc/dbschema.rst
@@ -18,13 +18,18 @@ The schema can change without changing the major version of coverage.py, so be
 careful when accessing the database directly.  The `coverage_schema` table has
 the schema number of the database.  The schema described here corresponds to:
 
-.. copied_from: coverage/sqldata.py
-
+.. [[[cog
+    from coverage.sqldata import SCHEMA_VERSION
+    print(".. code::")
+    print()
+    print(f"    SCHEMA_VERSION = {SCHEMA_VERSION}")
+    print()
+.. ]]]
 .. code::
 
     SCHEMA_VERSION = 7
 
-.. end_copied_from
+.. [[[end]]] (checksum: 95a75340df33237e7e9c93b02dd1814c)
 
 You can use SQLite tools such as the :mod:`sqlite3 <python:sqlite3>` module in
 the Python standard library to access the data.  Some data is stored in a
@@ -37,8 +42,13 @@ Database schema
 
 This is the database schema:
 
-.. copied_from: coverage/sqldata.py
-
+.. [[[cog
+    import textwrap
+    from coverage.sqldata import SCHEMA
+    print(".. code::")
+    print()
+    print(textwrap.indent(SCHEMA, "    "))
+.. ]]]
 .. code::
 
     CREATE TABLE coverage_schema (
@@ -101,7 +111,7 @@ This is the database schema:
         foreign key (file_id) references file (id)
     );
 
-.. end_copied_from
+.. [[[end]]] (checksum: 207fbab355481686e0dce0a9d99d173c)
 
 
 .. _numbits:
diff --git a/doc/help/annotate.rst b/doc/help/annotate.rst
deleted file mode 100644
index c8d59719..00000000
--- a/doc/help/annotate.rst
+++ /dev/null
@@ -1,28 +0,0 @@
-
-.. This file is auto-generated by "make dochtml", don't edit it manually.
-
-.. code::
-
-    $ coverage annotate --help
-    Usage: coverage annotate [options] [modules]
-
-    Make annotated copies of the given files, marking statements that are executed
-    with > and statements that are missed with !.
-
-    Options:
-      -d DIR, --directory=DIR
-                            Write the output files to DIR.
-      -i, --ignore-errors   Ignore errors while reading source files.
-      --include=PAT1,PAT2,...
-                            Include only files whose paths match one of these
-                            patterns. Accepts shell-style wildcards, which must be
-                            quoted.
-      --omit=PAT1,PAT2,...  Omit files whose paths match one of these patterns.
-                            Accepts shell-style wildcards, which must be quoted.
-      --debug=OPTS          Debug options, separated by commas. [env:
-                            COVERAGE_DEBUG]
-      -h, --help            Get help on this command.
-      --rcfile=RCFILE       Specify configuration file. By default '.coveragerc',
-                            'setup.cfg', 'tox.ini', and 'pyproject.toml' are
-                            tried. [env: COVERAGE_RCFILE]
-
diff --git a/doc/help/combine.rst b/doc/help/combine.rst
deleted file mode 100644
index 49c0e089..00000000
--- a/doc/help/combine.rst
+++ /dev/null
@@ -1,25 +0,0 @@
-
-.. This file is auto-generated by "make dochtml", don't edit it manually.
-
-.. code::
-
-    $ coverage combine --help
-    Usage: coverage combine [options] <path1> <path2> ... <pathN>
-
-    Combine data from multiple coverage files collected with 'run -p'.  The
-    combined results are written to a single file representing the union of the
-    data. The positional arguments are data files or directories containing data
-    files. If no paths are provided, data files in the default data file's
-    directory are combined.
-
-    Options:
-      -a, --append     Append coverage data to .coverage, otherwise it starts
-                       clean each time.
-      --keep           Keep original coverage files, otherwise they are deleted.
-      -q, --quiet      Don't print messages about what is happening.
-      --debug=OPTS     Debug options, separated by commas. [env: COVERAGE_DEBUG]
-      -h, --help       Get help on this command.
-      --rcfile=RCFILE  Specify configuration file. By default '.coveragerc',
-                       'setup.cfg', 'tox.ini', and 'pyproject.toml' are tried.
-                       [env: COVERAGE_RCFILE]
-
diff --git a/doc/help/debug.rst b/doc/help/debug.rst
deleted file mode 100644
index b6361da5..00000000
--- a/doc/help/debug.rst
+++ /dev/null
@@ -1,20 +0,0 @@
-
-.. This file is auto-generated by "make dochtml", don't edit it manually.
-
-.. code::
-
-    $ coverage debug --help
-    Usage: coverage debug <topic>
-
-    Display information about the internals of coverage.py, for diagnosing
-    problems. Topics are: 'data' to show a summary of the collected data; 'sys' to
-    show installation information; 'config' to show the configuration; 'premain'
-    to show what is calling coverage.
-
-    Options:
-      --debug=OPTS     Debug options, separated by commas. [env: COVERAGE_DEBUG]
-      -h, --help       Get help on this command.
-      --rcfile=RCFILE  Specify configuration file. By default '.coveragerc',
-                       'setup.cfg', 'tox.ini', and 'pyproject.toml' are tried.
-                       [env: COVERAGE_RCFILE]
-
diff --git a/doc/help/erase.rst b/doc/help/erase.rst
deleted file mode 100644
index 372dd4fb..00000000
--- a/doc/help/erase.rst
+++ /dev/null
@@ -1,17 +0,0 @@
-
-.. This file is auto-generated by "make dochtml", don't edit it manually.
-
-.. code::
-
-    $ coverage erase --help
-    Usage: coverage erase [options]
-
-    Erase previously collected coverage data.
-
-    Options:
-      --debug=OPTS     Debug options, separated by commas. [env: COVERAGE_DEBUG]
-      -h, --help       Get help on this command.
-      --rcfile=RCFILE  Specify configuration file. By default '.coveragerc',
-                       'setup.cfg', 'tox.ini', and 'pyproject.toml' are tried.
-                       [env: COVERAGE_RCFILE]
-
diff --git a/doc/help/html.rst b/doc/help/html.rst
deleted file mode 100644
index 081646b9..00000000
--- a/doc/help/html.rst
+++ /dev/null
@@ -1,42 +0,0 @@
-
-.. This file is auto-generated by "make dochtml", don't edit it manually.
-
-.. code::
-
-    $ coverage html --help
-    Usage: coverage html [options] [modules]
-
-    Create an HTML report of the coverage of the files.  Each file gets its own
-    page, with the source decorated to show executed, excluded, and missed lines.
-
-    Options:
-      --contexts=REGEX1,REGEX2,...
-                            Only display data from lines covered in the given
-                            contexts. Accepts Python regexes, which must be
-                            quoted.
-      -d DIR, --directory=DIR
-                            Write the output files to DIR.
-      --fail-under=MIN      Exit with a status of 2 if the total coverage is less
-                            than MIN.
-      -i, --ignore-errors   Ignore errors while reading source files.
-      --include=PAT1,PAT2,...
-                            Include only files whose paths match one of these
-                            patterns. Accepts shell-style wildcards, which must be
-                            quoted.
-      --omit=PAT1,PAT2,...  Omit files whose paths match one of these patterns.
-                            Accepts shell-style wildcards, which must be quoted.
-      --precision=N         Number of digits after the decimal point to display
-                            for reported coverage percentages.
-      -q, --quiet           Don't print messages about what is happening.
-      --show-contexts       Show contexts for covered lines.
-      --skip-covered        Skip files with 100% coverage.
-      --no-skip-covered     Disable --skip-covered.
-      --skip-empty          Skip files with no code.
-      --title=TITLE         A text string to use as the title on the HTML.
-      --debug=OPTS          Debug options, separated by commas. [env:
-                            COVERAGE_DEBUG]
-      -h, --help            Get help on this command.
-      --rcfile=RCFILE       Specify configuration file. By default '.coveragerc',
-                            'setup.cfg', 'tox.ini', and 'pyproject.toml' are
-                            tried. [env: COVERAGE_RCFILE]
-
diff --git a/doc/help/json.rst b/doc/help/json.rst
deleted file mode 100644
index 58f08948..00000000
--- a/doc/help/json.rst
+++ /dev/null
@@ -1,36 +0,0 @@
-
-.. This file is auto-generated by "make dochtml", don't edit it manually.
-
-.. code::
-
-    $ coverage json --help
-    Usage: coverage json [options] [modules]
-
-    Generate a JSON report of coverage results.
-
-    Options:
-      --contexts=REGEX1,REGEX2,...
-                            Only display data from lines covered in the given
-                            contexts. Accepts Python regexes, which must be
-                            quoted.
-      --fail-under=MIN      Exit with a status of 2 if the total coverage is less
-                            than MIN.
-      -i, --ignore-errors   Ignore errors while reading source files.
-      --include=PAT1,PAT2,...
-                            Include only files whose paths match one of these
-                            patterns. Accepts shell-style wildcards, which must be
-                            quoted.
-      --omit=PAT1,PAT2,...  Omit files whose paths match one of these patterns.
-                            Accepts shell-style wildcards, which must be quoted.
-      -o OUTFILE            Write the JSON report to this file. Defaults to
-                            'coverage.json'
-      --pretty-print        Format the JSON for human readers.
-      -q, --quiet           Don't print messages about what is happening.
-      --show-contexts       Show contexts for covered lines.
-      --debug=OPTS          Debug options, separated by commas. [env:
-                            COVERAGE_DEBUG]
-      -h, --help            Get help on this command.
-      --rcfile=RCFILE       Specify configuration file. By default '.coveragerc',
-                            'setup.cfg', 'tox.ini', and 'pyproject.toml' are
-                            tried. [env: COVERAGE_RCFILE]
-
diff --git a/doc/help/report.rst b/doc/help/report.rst
deleted file mode 100644
index b8985e4b..00000000
--- a/doc/help/report.rst
+++ /dev/null
@@ -1,40 +0,0 @@
-
-.. This file is auto-generated by "make dochtml", don't edit it manually.
-
-.. code::
-
-    $ coverage report --help
-    Usage: coverage report [options] [modules]
-
-    Report coverage statistics on modules.
-
-    Options:
-      --contexts=REGEX1,REGEX2,...
-                            Only display data from lines covered in the given
-                            contexts. Accepts Python regexes, which must be
-                            quoted.
-      --fail-under=MIN      Exit with a status of 2 if the total coverage is less
-                            than MIN.
-      -i, --ignore-errors   Ignore errors while reading source files.
-      --include=PAT1,PAT2,...
-                            Include only files whose paths match one of these
-                            patterns. Accepts shell-style wildcards, which must be
-                            quoted.
-      --omit=PAT1,PAT2,...  Omit files whose paths match one of these patterns.
-                            Accepts shell-style wildcards, which must be quoted.
-      --precision=N         Number of digits after the decimal point to display
-                            for reported coverage percentages.
-      --sort=COLUMN         Sort the report by the named column: name, stmts,
-                            miss, branch, brpart, or cover. Default is name.
-      -m, --show-missing    Show line numbers of statements in each module that
-                            weren't executed.
-      --skip-covered        Skip files with 100% coverage.
-      --no-skip-covered     Disable --skip-covered.
-      --skip-empty          Skip files with no code.
-      --debug=OPTS          Debug options, separated by commas. [env:
-                            COVERAGE_DEBUG]
-      -h, --help            Get help on this command.
-      --rcfile=RCFILE       Specify configuration file. By default '.coveragerc',
-                            'setup.cfg', 'tox.ini', and 'pyproject.toml' are
-                            tried. [env: COVERAGE_RCFILE]
-
diff --git a/doc/help/run.rst b/doc/help/run.rst
deleted file mode 100644
index 467764a6..00000000
--- a/doc/help/run.rst
+++ /dev/null
@@ -1,44 +0,0 @@
-
-.. This file is auto-generated by "make dochtml", don't edit it manually.
-
-.. code::
-
-    $ coverage run --help
-    Usage: coverage run [options] <pyfile> [program options]
-
-    Run a Python program, measuring code execution.
-
-    Options:
-      -a, --append          Append coverage data to .coverage, otherwise it starts
-                            clean each time.
-      --branch              Measure branch coverage in addition to statement
-                            coverage.
-      --concurrency=LIB     Properly measure code using a concurrency library.
-                            Valid values are: thread, gevent, greenlet, eventlet,
-                            multiprocessing.
-      --context=LABEL       The context label to record for this coverage run.
-      --include=PAT1,PAT2,...
-                            Include only files whose paths match one of these
-                            patterns. Accepts shell-style wildcards, which must be
-                            quoted.
-      -m, --module          <pyfile> is an importable Python module, not a script
-                            path, to be run as 'python -m' would run it.
-      --omit=PAT1,PAT2,...  Omit files whose paths match one of these patterns.
-                            Accepts shell-style wildcards, which must be quoted.
-      -L, --pylib           Measure coverage even inside the Python installed
-                            library, which isn't done by default.
-      -p, --parallel-mode   Append the machine name, process id and random number
-                            to the .coverage data file name to simplify collecting
-                            data from many processes.
-      --source=SRC1,SRC2,...
-                            A list of directories or importable names of code to
-                            measure.
-      --timid               Use a simpler but slower trace method. Try this if you
-                            get seemingly impossible results!
-      --debug=OPTS          Debug options, separated by commas. [env:
-                            COVERAGE_DEBUG]
-      -h, --help            Get help on this command.
-      --rcfile=RCFILE       Specify configuration file. By default '.coveragerc',
-                            'setup.cfg', 'tox.ini', and 'pyproject.toml' are
-                            tried. [env: COVERAGE_RCFILE]
-
diff --git a/doc/help/xml.rst b/doc/help/xml.rst
deleted file mode 100644
index cb64877d..00000000
--- a/doc/help/xml.rst
+++ /dev/null
@@ -1,31 +0,0 @@
-
-.. This file is auto-generated by "make dochtml", don't edit it manually.
-
-.. code::
-
-    $ coverage xml --help
-    Usage: coverage xml [options] [modules]
-
-    Generate an XML report of coverage results.
-
-    Options:
-      --fail-under=MIN      Exit with a status of 2 if the total coverage is less
-                            than MIN.
-      -i, --ignore-errors   Ignore errors while reading source files.
-      --include=PAT1,PAT2,...
-                            Include only files whose paths match one of these
-                            patterns. Accepts shell-style wildcards, which must be
-                            quoted.
-      --omit=PAT1,PAT2,...  Omit files whose paths match one of these patterns.
-                            Accepts shell-style wildcards, which must be quoted.
-      -o OUTFILE            Write the XML report to this file. Defaults to
-                            'coverage.xml'
-      -q, --quiet           Don't print messages about what is happening.
-      --skip-empty          Skip files with no code.
-      --debug=OPTS          Debug options, separated by commas. [env:
-                            COVERAGE_DEBUG]
-      -h, --help            Get help on this command.
-      --rcfile=RCFILE       Specify configuration file. By default '.coveragerc',
-                            'setup.cfg', 'tox.ini', and 'pyproject.toml' are
-                            tried. [env: COVERAGE_RCFILE]
-
diff --git a/doc/requirements.in b/doc/requirements.in
index fb3c27ad..3a9088c7 100644
--- a/doc/requirements.in
+++ b/doc/requirements.in
@@ -6,6 +6,7 @@
 
 -c ../requirements/pins.pip
 
+cogapp
 doc8
 pyenchant
 sphinx
diff --git a/doc/requirements.pip b/doc/requirements.pip
index 0025493b..276f4a99 100644
--- a/doc/requirements.pip
+++ b/doc/requirements.pip
@@ -12,6 +12,8 @@ certifi==2021.10.8
     # via requests
 charset-normalizer==2.0.7
     # via requests
+cogapp==3.3.0
+    # via -r doc/requirements.in
 colorama==0.4.4
     # via sphinx-autobuild
 doc8==0.10.1
@@ -97,5 +99,5 @@ urllib3==1.26.7
     # via requests
 
 # The following packages are considered to be unsafe in a requirements file:
-setuptools==59.1.1
+setuptools==59.2.0
     # via sphinx
diff --git a/requirements/dev.in b/requirements/dev.in
index df834108..44c2c39f 100644
--- a/requirements/dev.in
+++ b/requirements/dev.in
@@ -12,6 +12,7 @@ tox
 -r pytest.pip
 
 # for linting.
+cogapp
 greenlet
 pylint
 check-manifest
diff --git a/requirements/dev.pip b/requirements/dev.pip
index 06010a93..416df6a6 100644
--- a/requirements/dev.pip
+++ b/requirements/dev.pip
@@ -29,6 +29,8 @@ charset-normalizer==2.0.7
     # via requests
 check-manifest==0.47
     # via -r requirements/dev.in
+cogapp==3.3.0
+    # via -r requirements/dev.in
 colorama==0.4.4
     # via twine
 decorator==5.1.0
@@ -60,7 +62,7 @@ future==0.18.2
     #   pycontracts
 greenlet==1.1.2
     # via -r requirements/dev.in
-hypothesis==6.24.6
+hypothesis==6.25.0
     # via -r requirements/pytest.pip
 idna==3.3
     # via requests
@@ -95,7 +97,7 @@ parso==0.8.2
     # via jedi
 pep517==0.12.0
     # via build
-pkginfo==1.7.1
+pkginfo==1.8.1
     # via twine
 platformdirs==2.4.0
     # via
@@ -212,7 +214,7 @@ zipp==3.6.0
 # The following packages are considered to be unsafe in a requirements file:
 pip==21.3.1
     # via -r requirements/pip.pip
-setuptools==59.1.1
+setuptools==59.2.0
     # via
     #   astroid
     #   check-manifest
diff --git a/requirements/kit.pip b/requirements/kit.pip
index 4fba8c2e..24eb772e 100644
--- a/requirements/kit.pip
+++ b/requirements/kit.pip
@@ -35,5 +35,5 @@ wheel==0.37.0
     # via -r requirements/kit.in
 
 # The following packages are considered to be unsafe in a requirements file:
-setuptools==59.1.1
+setuptools==59.2.0
     # via -r requirements/kit.in
diff --git a/requirements/pip-tools.pip b/requirements/pip-tools.pip
index 3a5d1bdc..93f04661 100644
--- a/requirements/pip-tools.pip
+++ b/requirements/pip-tools.pip
@@ -18,5 +18,5 @@ wheel==0.37.0
 # The following packages are considered to be unsafe in a requirements file:
 pip==21.3.1
     # via pip-tools
-setuptools==59.1.1
+setuptools==59.2.0
     # via pip-tools
diff --git a/requirements/pytest.pip b/requirements/pytest.pip
index 1732be28..11dbcc19 100644
--- a/requirements/pytest.pip
+++ b/requirements/pytest.pip
@@ -18,7 +18,7 @@ flaky==3.7.0
     # via -r requirements/pytest.in
 future==0.18.2
     # via pycontracts
-hypothesis==6.24.6
+hypothesis==6.25.0
     # via -r requirements/pytest.in
 iniconfig==1.1.1
     # via pytest
diff --git a/tox.ini b/tox.ini
index 31162ac7..2bbaf911 100644
--- a/tox.ini
+++ b/tox.ini
@@ -64,8 +64,7 @@ deps =
 whitelist_externals =
     make
 commands =
-    make cmd_help
-    python doc/check_copied_from.py doc/*.rst
+    python -m cogapp -cP --check --verbosity=1 doc/*.rst
     doc8 -q --ignore-path 'doc/_*' doc CHANGES.rst README.rst
     sphinx-build -b html -aEnqW doc doc/_build/html
     rst2html.py --strict README.rst doc/_build/trash
@@ -83,6 +82,9 @@ setenv =
 commands =
     python -m tabnanny {env:LINTABLE}
     python igor.py check_eol
+    python -m cogapp -cP --check --verbosity=1 doc/*.rst
+    python -m cogapp -cP --check --verbosity=1 .github/workflows/*.yml
+    doc8 -q --ignore-path 'doc/_*' doc CHANGES.rst README.rst
     # If 'build -q' becomes a thing (https://github.com/pypa/build/issues/188),
     # this can be simplifed:
     python igor.py quietly "python -m build"