diff options
author | Ned Batchelder <ned@nedbatchelder.com> | 2020-07-04 10:34:45 -0400 |
---|---|---|
committer | Ned Batchelder <ned@nedbatchelder.com> | 2020-07-04 10:34:45 -0400 |
commit | c60118961ecb3543a9b71ca93513007e91318df4 (patch) | |
tree | 2fc485023e667dcaa64b1e536dc4bec9ff555e08 | |
parent | a97cf2c471324b7db4a76b14826f5026ec24cfd2 (diff) | |
download | python-coveragepy-git-c60118961ecb3543a9b71ca93513007e91318df4.tar.gz |
Add --help output to command docs, and other reorganization
-rw-r--r-- | .gitignore | 9 | ||||
-rw-r--r-- | Makefile | 30 | ||||
-rw-r--r-- | coverage/cmdline.py | 7 | ||||
-rw-r--r-- | doc/_static/coverage.css | 6 | ||||
-rw-r--r-- | doc/cmd.rst | 183 | ||||
-rw-r--r-- | doc/config.rst | 12 | ||||
-rw-r--r-- | doc/contexts.rst | 2 |
7 files changed, 152 insertions, 97 deletions
@@ -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 @@ -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. |