Add coverage

tools/telemetry/third_party/coverage/doc/index.rst

+.. Licensed under the Apache License: http://www.apache.org/licenses/LICENSE-2.0
+.. For details: https://bitbucket.org/ned/coveragepy/src/default/NOTICE.txt
+
+===========
+Coverage.py
+===========
+
+.. :history: 20090524T134300, brand new docs.
+.. :history: 20090613T164000, final touches for 3.0
+.. :history: 20090618T195900, minor tweaks
+.. :history: 20090707T205200, changes for 3.0.1
+.. :history: 20090913T084400, new command line syntax
+.. :history: 20091004T211900, version 3.1
+.. :history: 20091127T155100, version 3.2
+.. :history: 20091205T161429, version 3.2 for real.
+.. :history: 20100224T204700, version 3.3
+.. :history: 20100306T181500, version 3.3.1
+.. :history: 20100725T211700, updated for 3.4.
+.. :history: 20100820T151500, updated for 3.4b1.
+.. :history: 20100906T134700, updated for 3.4b2.
+.. :history: 20100919T163500, updated for 3.4 release.
+.. :history: 20110213T081200, claim true 3.2 compatibility.
+.. :history: 20110604T114800, update for 3.5b1
+.. :history: 20110629T082300, update for 3.5
+.. :history: 20110827T221800, update for 3.5.1b1
+.. :history: 20110923T081800, update for 3.5.1
+.. :history: 20120429T162100, updated for 3.5.2b1
+.. :history: 20120503T233800, updated for 3.5.2
+.. :history: 20120929T093500, updated for 3.5.3
+.. :history: 20121117T094900, Change from easy_install to pip.
+.. :history: 20121128T203700, Updated for 3.6b1.
+.. :history: 20121223T180600, Updated for 3.6b2.
+.. :history: 20121229T112300, Updated for 3.6b3.
+.. :history: 20130105T174000, Updated for 3.6
+.. :history: 20131005T210000, Updated for 3.7
+.. :history: 20131212T213300, Updated for 3.7.1
+.. :history: 20140924T073000, Updated for 4.0a1
+.. :history: 20150124T023900, Updated for 4.0a4
+.. :history: 20150216T201000, Updated for 4.0a5
+.. :history: 20150802T160200, Updated for 4.0b1
+.. :history: 20150822T092900, Updated for 4.0b2
+.. :history: 20150918T072700, Updated for 4.0
+
+
+Coverage.py is a tool for measuring code coverage of Python programs. It
+monitors your program, noting which parts of the code have been executed, then
+analyzes the source to identify code that could have been executed but was not.
+
+Coverage measurement is typically used to gauge the effectiveness of tests. It
+can show which parts of your code are being exercised by tests, and which are
+not.
+
+.. ifconfig:: not prerelease
+
+    The latest version is coverage.py 4.0, released 20 September 2015.
+    It is supported on Python versions 2.6, 2.7, 3.3, 3.4, and 3.5, as well
+    as PyPy 2.4 and 2.6, and PyPy3 2.4.
+
+.. ifconfig:: prerelease
+
+    The latest version is coverage.py 4.0b2, released 22 August 2015.
+    It is supported on Python versions 2.6, 2.7, 3.3, 3.4, and 3.5c1, as well
+    as PyPy 2.4 and 2.6, and PyPy3 2.4.
+    **This is a pre-release build.  The usual warnings about possible bugs apply.**
+    The latest stable version is coverage.py 3.7.1, `described here`_.
+
+.. _described here: http://nedbatchelder.com/code/coverage
+
+
+Quick start
+-----------
+
+Getting started is easy:
+
+#.  Install coverage.py from the `coverage.py page on the Python Package Index`_,
+    or by using "pip install coverage".  For a few more details, see
+    :ref:`install`.
+
+#.  Use ``coverage run`` to run your program and gather data:
+
+    .. code-block:: console
+
+        $ coverage run my_program.py arg1 arg2
+        blah blah ..your program's output.. blah blah
+
+#.  Use ``coverage report`` to report on the results:
+
+    .. code-block:: console
+
+        $ coverage report -m
+        Name                      Stmts   Miss  Cover   Missing
+        -------------------------------------------------------
+        my_program.py                20      4    80%   33-35, 39
+        my_other_module.py           56      6    89%   17-23
+        -------------------------------------------------------
+        TOTAL                        76     10    87%
+
+#.  For a nicer presentation, use ``coverage html`` to get annotated HTML
+    listings detailing missed lines:
+
+    .. code-block:: console
+
+        $ coverage html
+
+    .. ifconfig:: not prerelease
+
+        Then visit htmlcov/index.html in your browser, to see a
+        `report like this`_.
+
+    .. ifconfig:: prerelease
+
+        Then visit htmlcov/index.html in your browser, to see a
+        `report like this one`_.
+
+.. _coverage.py page on the Python Package Index: http://pypi.python.org/pypi/coverage
+.. _report like this: http://nedbatchelder.com/files/sample_coverage_html/index.html
+.. _report like this one: http://nedbatchelder.com/files/sample_coverage_html_beta/index.html
+
+
+Using coverage.py
+-----------------
+
+There are a few different ways to use coverage.py.  The simplest is the
+:ref:`command line <cmd>`, which lets you run your program and see the results.
+If you need more control over how your project is measured, you can use the
+:ref:`API <api>`.
+
+Some test runners provide coverage integration to make it easy to use
+coverage.py while running tests.  For example, `nose`_ has a `cover plug-in`_.
+
+You can fine-tune coverage.py's view of your code by directing it to ignore
+parts that you know aren't interesting.  See :ref:`source` and :ref:`excluding`
+for details.
+
+.. _nose:           http://somethingaboutorange.com/mrl/projects/nose
+.. _cover plug-in:  https://nose.readthedocs.org/en/latest/plugins/cover.html
+
+
+.. _contact:
+
+Getting help
+------------
+
+If the :ref:`FAQ <faq>` doesn't answer your question, you can discuss
+coverage.py or get help using it on the `Testing In Python`_ mailing list.
+
+.. _Testing In Python: http://lists.idyll.org/listinfo/testing-in-python
+
+Bug reports are gladly accepted at the `Bitbucket issue tracker`_.
+Bitbucket also hosts the `code repository`_. There is a `mirrored repo`_ on
+GitHub.
+
+.. _Bitbucket issue tracker: http://bitbucket.org/ned/coveragepy/issues
+.. _code repository: http://bitbucket.org/ned/coveragepy
+.. _mirrored repo: https://github.com/nedbat/coveragepy
+
+`I can be reached`_ in a number of ways. I'm happy to answer questions about
+using coverage.py.
+
+.. _I can be reached:  http://nedbatchelder.com/site/aboutned.html
+
+
+
+More information
+----------------
+
+.. toctree::
+    :maxdepth: 1
+
+    install
+    cmd
+    config
+    source
+    excluding
+    branch
+    subprocess
+    api
+    howitworks
+    plugins
+    contributing
+    trouble
+    faq
+    changes