diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/cmd.rst | 18 | ||||
| -rw-r--r-- | doc/help/annotate.rst | 26 | ||||
| -rw-r--r-- | doc/help/combine.rst | 21 | ||||
| -rw-r--r-- | doc/help/debug.rst | 18 | ||||
| -rw-r--r-- | doc/help/erase.rst | 15 | ||||
| -rw-r--r-- | doc/help/html.rst | 39 | ||||
| -rw-r--r-- | doc/help/json.rst | 33 | ||||
| -rw-r--r-- | doc/help/report.rst | 38 | ||||
| -rw-r--r-- | doc/help/run.rst | 42 | ||||
| -rw-r--r-- | doc/help/xml.rst | 28 |
10 files changed, 269 insertions, 9 deletions
diff --git a/doc/cmd.rst b/doc/cmd.rst index 1edc19c6..b294ee8d 100644 --- a/doc/cmd.rst +++ b/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: diff --git a/doc/help/annotate.rst b/doc/help/annotate.rst new file mode 100644 index 00000000..fb80e12e --- /dev/null +++ b/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] + diff --git a/doc/help/combine.rst b/doc/help/combine.rst new file mode 100644 index 00000000..bf15c23f --- /dev/null +++ b/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] + diff --git a/doc/help/debug.rst b/doc/help/debug.rst new file mode 100644 index 00000000..7c71e90e --- /dev/null +++ b/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] + diff --git a/doc/help/erase.rst b/doc/help/erase.rst new file mode 100644 index 00000000..2bb64800 --- /dev/null +++ b/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] + diff --git a/doc/help/html.rst b/doc/help/html.rst new file mode 100644 index 00000000..5be94711 --- /dev/null +++ b/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] + diff --git a/doc/help/json.rst b/doc/help/json.rst new file mode 100644 index 00000000..4028788f --- /dev/null +++ b/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] + diff --git a/doc/help/report.rst b/doc/help/report.rst new file mode 100644 index 00000000..97f31777 --- /dev/null +++ b/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] + diff --git a/doc/help/run.rst b/doc/help/run.rst new file mode 100644 index 00000000..07f94aa5 --- /dev/null +++ b/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] + diff --git a/doc/help/xml.rst b/doc/help/xml.rst new file mode 100644 index 00000000..f83f297b --- /dev/null +++ b/doc/help/xml.rst @@ -0,0 +1,28 @@ + +.. 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' + --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] + |