Help in docs didn't work with tmp

Author: nedbat

Makefile

@@ -138,18 +138,17 @@ $(DOCBIN):
 	tox -q -e doc --notest
 
 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; \
+		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/^/    /' \
-			>> tmp/$$cmd.rst; \
+			>> doc/help/$$cmd.rst; \
 	done
 
 dochtml: $(DOCBIN) cmd_help		## Build the docs HTML output.

doc/cmd.rst

@@ -90,7 +90,7 @@ Python ``-m`` switch::
 
 There are many options:
 
-.. include:: ../tmp/run.rst
+.. include:: help/run.rst
 
 If you want :ref:`branch coverage <branch>` measurement, use the ``--branch``
 flag.  Otherwise only statement coverage is measured.
@@ -287,7 +287,7 @@ 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
+.. include:: help/combine.rst
 
 
 .. _cmd_erase:
@@ -297,7 +297,7 @@ Erase data: ``coverage erase``
 
 To erase the collected data, use the **erase** command:
 
-.. include:: ../tmp/erase.rst
+.. include:: help/erase.rst
 
 If your configuration file indicates parallel data collection, **erase** will
 remove all of the data files.
@@ -351,7 +351,7 @@ 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
+.. include:: help/report.rst
 
 The ``-m`` flag also shows the line numbers of missing statements::
 
@@ -426,7 +426,7 @@ 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
+.. include:: help/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
@@ -470,7 +470,7 @@ compatible with `Cobertura`_.
 
 .. _Cobertura: http://cobertura.github.io/cobertura/
 
-.. include:: ../tmp/xml.rst
+.. include:: help/xml.rst
 
 You can specify the name of the output file with the ``-o`` switch.
 
@@ -484,7 +484,7 @@ JSON reporting: ``coverage json``
 
 The **json** command writes coverage data to a "coverage.json" file.
 
-.. include:: ../tmp/json.rst
+.. include:: help/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.
@@ -521,7 +521,7 @@ For example::
     >     else:
     >         a = 2
 
-.. include:: ../tmp/annotate.rst
+.. include:: help/annotate.rst
 
 Other common reporting options are described above in :ref:`cmd_reporting`.
 
@@ -544,7 +544,7 @@ 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
+.. include:: help/debug.rst
 
 .. _cmd_run_debug:
 

doc/help/annotate.rst

@@ -0,0 +1,26 @@
+
+.. 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]
+    

doc/help/combine.rst

@@ -0,0 +1,21 @@
+
+.. 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.
+      --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]
+    

doc/help/debug.rst

@@ -0,0 +1,18 @@
+
+.. 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]
+    

doc/help/erase.rst

@@ -0,0 +1,15 @@
+
+.. 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]
+    

doc/help/html.rst

@@ -0,0 +1,39 @@
+
+.. 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.
+      --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]
+    

doc/help/json.rst

@@ -0,0 +1,33 @@
+
+.. 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.
+      --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]
+    

doc/help/report.rst

@@ -0,0 +1,38 @@
+
+.. 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]
+    

doc/help/run.rst

@@ -0,0 +1,42 @@
+
+.. 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 packages or directories of code to be
+                            measured.
+      --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]
+