Add --help output to command docs, and other reorganization

7 files changed, 152 insertions, 97 deletions

diff --git a/.gitignore b/.gitignore
index 971e9b84..f8813653 100644
--- a/.gitignore
+++ b/.gitignore
@@ -35,9 +35,12 @@ covmain.zip
 zipmods.zip
 
 # Stuff in the doc directory.
-_build
-_spell
-sample_html_beta
+doc/_build
+doc/_spell
+doc/sample_html_beta
+
+# Build intermediaries.
+tmp
 
 # Stuff in the ci directory.
 *.token
diff --git a/Makefile b/Makefile
index 64eab8be..3589c10b 100644
--- a/Makefile
+++ b/Makefile
@@ -28,6 +28,7 @@ clean: clean_platform                   ## Remove artifacts of test execution, i
 	rm -rf tests/eggsrc/build tests/eggsrc/dist tests/eggsrc/*.egg-info
 	rm -f setuptools-*.egg distribute-*.egg distribute-*.tar.gz
 	rm -rf doc/_build doc/_spell doc/sample_html_beta
+	rm -rf tmp
 	rm -rf .cache .pytest_cache .hypothesis
 	rm -rf $$TMPDIR/coverage_test
 	-make -C tests/gold/html clean
@@ -133,10 +134,25 @@ WEBHOME = ~/web/stellated/
 WEBSAMPLE = $(WEBHOME)/files/sample_coverage_html
 WEBSAMPLEBETA = $(WEBHOME)/files/sample_coverage_html_beta
 
-$(DOCPYTHON):
+$(DOCBIN):
 	tox -q -e doc --notest
 
-dochtml: $(DOCBIN)			## Build the docs HTML output.
+cmd_help: $(DOCBIN)
+	mkdir -p tmp
+	for cmd in annotate combine debug erase html json report run xml; do \
+		echo > tmp/$$cmd.rst; \
+		echo ".. code::" >> tmp/$$cmd.rst; \
+		echo >> tmp/$$cmd.rst; \
+		echo "    $$ coverage $$cmd --help" >> tmp/$$cmd.rst; \
+		$(DOCBIN)/python -m coverage $$cmd --help | \
+		sed \
+			-e 's/__main__.py/coverage/' \
+			-e '/^Full doc/d' \
+			-e 's/^/    /' \
+			>> tmp/$$cmd.rst; \
+	done
+
+dochtml: $(DOCBIN) cmd_help		## Build the docs HTML output.
 	$(DOCBIN)/python doc/check_copied_from.py doc/*.rst
 	$(SPHINXBUILD) -b html doc doc/_build/html
 
@@ -156,16 +172,16 @@ publishbeta:
 	mkdir -p $(WEBSAMPLEBETA)
 	cp doc/sample_html_beta/*.* $(WEBSAMPLEBETA)
 
-CHANGES_MD = /tmp/rst_rst/changes.md
-RELNOTES_JSON = /tmp/relnotes.json
+CHANGES_MD = tmp/rst_rst/changes.md
+RELNOTES_JSON = tmp/relnotes.json
 
 $(CHANGES_MD): CHANGES.rst $(DOCBIN)
-	$(SPHINXBUILD) -b rst doc /tmp/rst_rst
-	pandoc -frst -tmarkdown_strict --atx-headers --wrap=none /tmp/rst_rst/changes.rst > $(CHANGES_MD)
+	$(SPHINXBUILD) -b rst doc tmp/rst_rst
+	pandoc -frst -tmarkdown_strict --atx-headers --wrap=none tmp/rst_rst/changes.rst > $(CHANGES_MD)
 
 relnotes_json: $(RELNOTES_JSON)
 $(RELNOTES_JSON): $(CHANGES_MD)
-	$(DOCBIN)/python ci/parse_relnotes.py /tmp/rst_rst/changes.md $(RELNOTES_JSON)
+	$(DOCBIN)/python ci/parse_relnotes.py tmp/rst_rst/changes.md $(RELNOTES_JSON)
 
 tidelift_relnotes: $(RELNOTES_JSON)	## Upload parsed release notes to Tidelift.
 	$(DOCBIN)/python ci/tidelift_relnotes.py $(RELNOTES_JSON) pypi/coverage
diff --git a/coverage/cmdline.py b/coverage/cmdline.py
index f7c82864..487f9699 100644
--- a/coverage/cmdline.py
+++ b/coverage/cmdline.py
@@ -351,8 +351,11 @@ CMDS = {
         description=(
             "Display information on the internals of coverage.py, "
             "for diagnosing problems. "
-            "Topics are 'data' to show a summary of the collected data, "
-            "or 'sys' to show installation information."
+            "Topics are: "
+                "'data' to show a summary of the collected data; "
+                "'sys' to show installation information; "
+                "'config' to show the configuration; "
+                "or 'premain' to show what is calling coverage."
         ),
     ),
 
diff --git a/doc/_static/coverage.css b/doc/_static/coverage.css
index 15a55508..482936ab 100644
--- a/doc/_static/coverage.css
+++ b/doc/_static/coverage.css
@@ -15,10 +15,6 @@ img.tideliftlogo {
     margin-top: .5em !important;
 }
 
-.rst-content div[class^="highlight"] {
-    margin-bottom: 12px;
-}
-
 .rst-content ol.arabic li {
     margin-bottom: 12px;
 }
@@ -46,11 +42,11 @@ img.tideliftlogo {
 
 .rst-content pre.literal-block {
     white-space: pre;
-    margin: 0 !important;
     padding: 12px 12px !important;
     font-family: Consolas,"Andale Mono WT","Andale Mono","Lucida Console","Lucida Sans Typewriter","DejaVu Sans Mono","Bitstream Vera Sans Mono","Liberation Mono","Nimbus Mono L",Monaco,"Courier New",Courier,monospace;
     font-size: 12px;
     display: block;
     overflow: auto;
     color: #404040;
+    background: #efc;
 }
diff --git a/doc/cmd.rst b/doc/cmd.rst
index 344025da..1edc19c6 100644
--- a/doc/cmd.rst
+++ b/doc/cmd.rst
@@ -3,38 +3,40 @@
 
 .. _cmd:
 
-==============================
-Coverage.py command line usage
-==============================
+==================
+Command line usage
+==================
 
 .. highlight:: console
 
-When you install coverage.py, a command-line script simply called ``coverage``
-is placed in your Python scripts directory.  To help with multi-version
-installs, it will also create either a ``coverage2`` or ``coverage3`` alias,
-and a ``coverage-X.Y`` alias, depending on the version of Python you're using.
-For example, when installing on Python 3.7, you will be able to use
-``coverage``, ``coverage3``, or ``coverage-3.7`` on the command line.
+When you install coverage.py, a command-line script called ``coverage`` is
+placed on your path.  To help with multi-version installs, it will also create
+either a ``coverage2`` or ``coverage3`` alias, and a ``coverage-X.Y`` alias,
+depending on the version of Python you're using.  For example, when installing
+on Python 3.7, you will be able to use ``coverage``, ``coverage3``, or
+``coverage-3.7`` on the command line.
 
-Coverage.py has a number of commands which determine the action performed:
+Coverage.py has a number of commands:
 
-* **run** -- Run a Python program and collect execution data.
+* **run** -- :ref:`Run a Python program and collect execution data <cmd_run>`.
 
-* **report** -- Report coverage results.
+* **combine** -- :ref:`Combine together a number of data files <cmd_combine>`.
 
-* **html** -- Produce annotated HTML listings with coverage results.
+* **erase** -- :ref:`Erase previously collected coverage data <cmd_erase>`.
 
-* **json** -- Produce a JSON report with coverage results.
+* **report** -- :ref:`Report coverage results <cmd_report>`.
 
-* **xml** -- Produce an XML report with coverage results.
+* **html** --
+  :ref:`Produce annotated HTML listings with coverage results <cmd_html>`.
 
-* **annotate** -- Annotate source files with coverage results.
+* **xml** -- :ref:`Produce an XML report with coverage results <cmd_xml>`.
 
-* **erase** -- Erase previously collected coverage data.
+* **json** -- :ref:`Produce a JSON report with coverage results <cmd_json>`.
 
-* **combine** -- Combine together a number of data files.
+* **annotate** --
+  :ref:`Annotate source files with coverage results <cmd_annotate>`.
 
-* **debug** -- Get diagnostic information.
+* **debug** -- :ref:`Get diagnostic information <cmd_debug>`.
 
 Help is available with the **help** command, or with the ``--help`` switch on
 any other command::
@@ -44,7 +46,13 @@ any other command::
     $ coverage run --help
 
 Version information for coverage.py can be displayed with
-``coverage --version``.
+``coverage --version``:
+
+.. parsed-literal::
+
+    $ coverage --version
+    Coverage.py, version |release| with C extension
+    Documentation at |doc-url|
 
 Any command can use a configuration file by specifying it with the
 ``--rcfile=FILE`` command-line switch.  Any option you can set on the command
@@ -56,8 +64,8 @@ runner plugins) may not offer. See :ref:`config` for more details.
 
 .. _cmd_run:
 
-Execution
----------
+Execution: ``coverage run``
+---------------------------
 
 You collect execution data by running your Python program with the **run**
 command::
@@ -80,6 +88,10 @@ Python ``-m`` switch::
     you are trying to measure. The test runner will run your tests and coverage
     will measure the coverage of your code along the way.
 
+There are many options:
+
+.. include:: ../tmp/run.rst
+
 If you want :ref:`branch coverage <branch>` measurement, use the ``--branch``
 flag.  Otherwise only statement coverage is measured.
 
@@ -111,7 +123,7 @@ configuration file for all options.
 
 If you are measuring coverage in a multi-process program, or across a number of
 machines, you'll want the ``--parallel-mode`` switch to keep the data separate
-during measurement.  See :ref:`cmd_combining` below.
+during measurement.  See :ref:`cmd_combine` below.
 
 You can specify a :ref:`static context <contexts>` for a coverage run with
 ``--context``.  This can be any label you want, and will be recorded with the
@@ -129,7 +141,7 @@ simpler but slower trace method, and might be needed in rare cases.
 .. _cmd_warnings:
 
 Warnings
---------
+........
 
 During execution, coverage.py may warn you about conditions it detects that
 could affect the measurement process.  The possible warnings include:
@@ -196,7 +208,7 @@ collected," add this to your .coveragerc file::
 .. _cmd_datafile:
 
 Data file
----------
+.........
 
 Coverage.py collects execution data in a file called ".coverage".  If need be,
 you can set a new file name with the COVERAGE_FILE environment variable.  This
@@ -207,15 +219,11 @@ to run your program multiple times to get complete data (for example, because
 you need to supply different options), you can accumulate data across runs with
 the ``--append`` flag on the **run** command.
 
-To erase the collected data, use the **erase** command::
-
-    $ coverage erase
 
+.. _cmd_combine:
 
-.. _cmd_combining:
-
-Combining data files
---------------------
+Combining data files: ``coverage combine``
+------------------------------------------
 
 Often test suites are run under different conditions, for example, with
 different versions of Python, or dependencies, or on different operating
@@ -279,6 +287,21 @@ setting to store relative file paths (see :ref:`relative_files
 If any of the data files can't be read, coverage.py will print a warning
 indicating the file and the problem.
 
+.. include:: ../tmp/combine.rst
+
+
+.. _cmd_erase:
+
+Erase data: ``coverage erase``
+------------------------------
+
+To erase the collected data, use the **erase** command:
+
+.. include:: ../tmp/erase.rst
+
+If your configuration file indicates parallel data collection, **erase** will
+remove all of the data files.
+
 
 .. _cmd_reporting:
 
@@ -308,10 +331,10 @@ can be used as part of a pass/fail condition, for example in a continuous
 integration server.  This option isn't available for **annotate**.
 
 
-.. _cmd_summary:
+.. _cmd_report:
 
-Coverage summary
-----------------
+Coverage summary: ``coverage report``
+-------------------------------------
 
 The simplest reporting is a textual summary produced with **report**::
 
@@ -328,6 +351,8 @@ 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:: ../tmp/report.rst
+
 The ``-m`` flag also shows the line numbers of missing statements::
 
     $ coverage report -m
@@ -382,8 +407,8 @@ Other common reporting options are described above in :ref:`cmd_reporting`.
 
 .. _cmd_html:
 
-HTML annotation
----------------
+HTML annotation: ``coverage html``
+----------------------------------
 
 Coverage.py can annotate your source code for which lines were executed
 and which were not.  The **html** command creates an HTML report similar to the
@@ -401,6 +426,8 @@ 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:: ../tmp/html.rst
+
 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
 the command line.
@@ -433,10 +460,42 @@ annotate lines with the contexts that ran them.  See :ref:`context_reporting`
 for details.
 
 
-.. _cmd_annotation:
+.. _cmd_xml:
+
+XML reporting: ``coverage xml``
+-------------------------------
+
+The **xml** command writes coverage data to a "coverage.xml" file in a format
+compatible with `Cobertura`_.
 
-Text annotation
----------------
+.. _Cobertura: http://cobertura.github.io/cobertura/
+
+.. include:: ../tmp/xml.rst
+
+You can specify the name of the output file with the ``-o`` switch.
+
+Other common reporting options are described above in :ref:`cmd_reporting`.
+
+
+.. _cmd_json:
+
+JSON reporting: ``coverage json``
+---------------------------------
+
+The **json** command writes coverage data to a "coverage.json" file.
+
+.. include:: ../tmp/json.rst
+
+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.
+
+Other common reporting options are described above in :ref:`cmd_reporting`.
+
+
+.. _cmd_annotate:
+
+Text annotation: ``coverage annotate``
+--------------------------------------
 
 The **annotate** command produces a text annotation of your source code.  With
 a ``-d`` argument specifying an output directory, each Python file becomes a
@@ -462,41 +521,15 @@ For example::
     >     else:
     >         a = 2
 
-Other common reporting options are described above in :ref:`cmd_reporting`.
-
-
-.. _cmd_xml:
-
-XML reporting
--------------
-
-The **xml** command writes coverage data to a "coverage.xml" file in a format
-compatible with `Cobertura`_.
-
-.. _Cobertura: http://cobertura.github.io/cobertura/
-
-You can specify the name of the output file with the ``-o`` switch.
-
-Other common reporting options are described above in :ref:`cmd_reporting`.
-
-
-.. _cmd_json:
-
-JSON reporting
---------------
-
-The **json** command writes coverage data to a "coverage.json" file.
-
-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.
+.. include:: ../tmp/annotate.rst
 
 Other common reporting options are described above in :ref:`cmd_reporting`.
 
 
 .. _cmd_debug:
 
-Diagnostics
------------
+Diagnostics: ``coverage debug``
+-------------------------------
 
 The **debug** command shows internal information to help diagnose problems.
 If you are reporting a bug about coverage.py, including the output of this
@@ -511,13 +544,17 @@ Three types of information are available:
 * ``data``: show a summary of the collected coverage data
 * ``premain``: show the call stack invoking coverage
 
+.. include:: ../tmp/debug.rst
 
 .. _cmd_run_debug:
 
-The ``--debug`` option is available on all commands.  It instructs coverage.py
-to log internal details of its operation, to help with diagnosing problems.  It
-takes a comma-separated list of options, each indicating a facet of operation
-to log:
+``--debug``
+...........
+
+The ``--debug`` option is also available on all commands.  It instructs
+coverage.py to log internal details of its operation, to help with diagnosing
+problems.  It takes a comma-separated list of options, each indicating a facet
+of operation to log:
 
 * ``callers``: annotate each debug message with a stack trace of the callers
   to that point.
diff --git a/doc/config.rst b/doc/config.rst
index bac2f0bd..6a0dbcf8 100644
--- a/doc/config.rst
+++ b/doc/config.rst
@@ -186,7 +186,7 @@ of measurement or reporting.  See :ref:`source` for details.
 
 ``parallel`` (boolean, default False): append the machine name, process
 id and random number to the data file name to simplify collecting data from
-many processes.  See :ref:`cmd_combining` for more information.
+many processes.  See :ref:`cmd_combine` for more information.
 
 .. _config_run_plugins:
 
@@ -197,7 +197,7 @@ for more information.
 
 ``relative_files`` (boolean, default False): *Experimental*: store relative
 file paths in the data file.  This makes it easier to measure code in one (or
-multiple) environments, and then report in another. See :ref:`cmd_combining`
+multiple) environments, and then report in another. See :ref:`cmd_combine`
 for details.
 
 .. versionadded:: 5.0
@@ -246,7 +246,7 @@ against the source file found at "src/module.py".
 If you specify more than one list of paths, they will be considered in order.
 The first list that has a match will be used.
 
-See :ref:`cmd_combining` for more information.
+See :ref:`cmd_combine` for more information.
 
 
 .. _config_report:
@@ -305,17 +305,17 @@ setting also affects the interpretation of the ``fail_under`` setting.
 .. _config_report_show_missing:
 
 ``show_missing`` (boolean, default False): when running a summary report, show
-missing lines.  See :ref:`cmd_summary` for more information.
+missing lines.  See :ref:`cmd_report` for more information.
 
 .. _config_report_skip_covered:
 
 ``skip_covered`` (boolean, default False): Don't include files in the report
-that are 100% covered files. See :ref:`cmd_summary` for more information.
+that are 100% covered files. See :ref:`cmd_report` for more information.
 
 .. _config_report_skip_empty:
 
 ``skip_empty`` (boolean, default False): Don't include empty files (those that
-have 0 statements) in the report. See :ref:`cmd_summary` for more information.
+have 0 statements) in the report. See :ref:`cmd_report` for more information.
 
 .. _config_report_sort:
 
diff --git a/doc/contexts.rst b/doc/contexts.rst
index 0d1cfe1e..1ea45d46 100644
--- a/doc/contexts.rst
+++ b/doc/contexts.rst
@@ -26,7 +26,7 @@ A static context is set by an option when you run coverage.py.  The value is
 fixed for the duration of a run.  They can be any text you like, for example,
 "python3" or "with_numpy".  The context is recorded with the data.
 
-When you :ref:`combine multiple data files <cmd_combining>` together, they can
+When you :ref:`combine multiple data files <cmd_combine>` together, they can
 have differing contexts.  All of the information is retained, so that the
 different contexts are correctly recorded in the combined file.