Add coverage

tools/telemetry/third_party/coverage/doc/python-coverage.1.txt

+===============
+python-coverage
+===============
+
+-------------------------------------------------
+measure code coverage of Python program execution
+-------------------------------------------------
+
+:Author: Ned Batchelder <ned@nedbatchelder.com>
+:Author: |author|
+:Date: 2015-09-20
+:Copyright: Apache 2.0 license, attribution and disclaimer required.
+:Manual section: 1
+:Manual group: Coverage.py
+
+..  |command| replace:: **python-coverage**
+
+..
+    To test this file:
+    $ rst2man < doc/python-coverage.1.txt  | groff -man -Tascii
+
+
+SYNOPSIS
+========
+
+| |command| `command` [ `option` ... ]
+| |command| **help** [ `command` ]
+
+
+DESCRIPTION
+===========
+
+|command| executes a Python program and measures which of its statements are
+executed and which are not, and reports these coverage measurements.
+
+
+COMMAND OVERVIEW
+================
+
+|command| **annotate**
+    Annotate source files with execution information.
+
+|command| **combine**
+    Combine a number of data files.
+
+|command| **erase**
+    Erase previously collected coverage data.
+
+|command| **help**
+    Get help on using coverage.py.
+
+|command| **html**
+    Create an HTML report.
+
+|command| **report**
+    Report coverage stats on modules.
+
+|command| **run**
+    Run a Python program and measure code execution.
+
+|command| **xml**
+    Create an XML report of coverage results.
+
+
+GLOBAL OPTIONS
+==============
+
+**--help**, **-h**
+    Describe how to use coverage.py, in general or a command.
+
+**--rcfile** `RCFILE`
+    Specify configuration file `RCFILE`. Defaults to ``.coveragerc``.
+
+**--omit** `PATTERN` [ , ... ]
+    Omit files when their file name matches one of these PATTERNs.
+    Usually needs quoting on the command line.
+
+**--include** `PATTERN` [ , ... ]
+    Include only files whose paths match one of these
+    PATTERNs. Accepts shell-style wildcards, which must be quoted.
+
+**--debug** `DEBUGOPT`,...
+    Debug options `DEBUGOPT`, separated by commas.
+
+
+
+COMMAND REFERENCE
+=================
+
+**annotate**
+
+    Options:
+
+    \-d `DIR`, --directory=`DIR`
+        Write the output files to DIR.
+
+    \-i, --ignore-errors
+        Ignore errors while reading source files.
+
+**combine** [ `PATH` ... ]
+
+    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.
+
+    If `PATH` is specified, they are files or directories containing data to
+    be combined.
+
+**erase**
+
+    Erase previously collected coverage data.
+
+**help** [ `command` ]
+
+    Describe how to use coverage.py.
+
+**html** [ `option` ... ] [ `MODULE` ... ]
+
+    Create an HTML report of the coverage of each `MODULE` file. Each file
+    gets its own page, with the source decorated to show executed,
+    excluded, and missed lines.
+
+    Options:
+
+    \-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.
+
+    \--title `TITLE`
+        Use the text string `TITLE` as the title on the HTML.
+
+**report** [ `option` ... ] [ `MODULE` ... ]
+
+    Report coverage statistics on each `MODULE`.
+
+    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.
+
+    \-m, --show-missing
+        Show line numbers of statements in each module that weren't
+        executed.
+
+    \--skip-covered
+        Skip files with 100% coverage.
+
+**run** [ `options` ... ] `PROGRAMFILE` [ `program_options` ]
+
+    Run a Python program `PROGRAMFILE`, measuring code execution.
+
+    Options:
+
+    \-a, --append
+        Append coverage data to .coverage, otherwise it is started clean
+        with each run.
+
+    \--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.
+
+    \-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 `SOURCE` ...
+        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!
+
+**xml** [ `options` ... ] [ `MODULES` ... ]
+
+    Generate an XML report of coverage results on each `MODULE`.
+
+    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.
+
+    \-o `OUTFILE`
+        Write the XML report to `OUTFILE`. Defaults to ``coverage.xml``.
+
+
+ENVIRONMENT VARIABLES
+=====================
+
+COVERAGE_FILE
+
+    Path to the file where coverage measurements are collected to and
+    reported from. Default: ``.coverage`` in the current working directory.
+
+HISTORY
+=======
+
+The |command| command is a Python program which calls the ``coverage``
+Python library to do all the work.
+
+The library was originally developed by Gareth Rees, and is now developed
+by Ned Batchelder.
+
+This manual page was written by |author|.
+
+..  |author| replace:: |authorname| |authoremail|
+..  |authorname| replace:: Ben Finney
+..  |authoremail| replace:: <ben+python@benfinney.id.au>
+
+..
+    Local variables:
+    mode: rst
+    coding: utf-8
+    time-stamp-format: "%:y-%02m-%02d"
+    time-stamp-start: "^:Date:[         ]+"
+    time-stamp-end: "$"
+    time-stamp-line-limit: 20
+    End:
+    vim: filetype=rst fileencoding=utf-8 :