diff options
| -rw-r--r-- | doc/cmd.rst | 53 | ||||
| -rw-r--r-- | doc/index.rst | 26 | ||||
| -rw-r--r-- | doc/install.rst | 32 |
3 files changed, 78 insertions, 33 deletions
diff --git a/doc/cmd.rst b/doc/cmd.rst index 053ed13..fa2f066 100644 --- a/doc/cmd.rst +++ b/doc/cmd.rst @@ -10,7 +10,7 @@ Coverage command line usage :history: 20091004T170700, changes for 3.1 :history: 20091127T200700, changes for 3.2 :history: 20100223T200600, changes for 3.3 -:history: 20100725T211700, updated for 3.4. +:history: 20100725T211700, updated for 3.4 .. highlight:: console @@ -35,8 +35,12 @@ which determine the action performed: * **debug** -- Get diagnostic information. -Help is available with ``coverage help``, or with the ``--help`` switch on any -other command. +Help is available with the **help** command, or with the ``--help`` switch on +any other command:: + + $ coverage help + $ coverage help run + $ coverage run --help Version information for coverage.py can be displayed with ``coverage --version``. @@ -55,7 +59,7 @@ Execution --------- You collect execution data by running your Python program with the **run** -coverage command:: +command:: $ coverage run my_program.py arg1 arg2 blah blah ..your program's output.. blah blah @@ -127,8 +131,8 @@ data file:: Reporting --------- -Coverage provides a few styles of reporting, with the ``report``, ``html``, -``annotate``, and ``xml`` commands. They share a number of common options. +Coverage provides a few styles of reporting, with the **report**, **html**, +**annotate**, and **xml** commands. They share a number of common options. The command-line arguments are module or file names to report on, if you'd like to report on a subset of the data collected. @@ -152,39 +156,39 @@ Coverage summary The simplest reporting is a textual summary produced with **report**:: $ coverage report - Name Stmts Exec Cover + Name Stmts Miss Cover --------------------------------------------- - my_program 20 16 80% - my_module 15 13 86% - my_other_module 56 50 89% + my_program 20 4 80% + my_module 15 2 86% + my_other_module 56 6 89% --------------------------------------------- - TOTAL 91 79 87% + TOTAL 91 12 87% For each module executed, the report shows the count of executable statements, -the number of those statements executed, and the resulting coverage, expressed +the number of those statements missed, and the resulting coverage, expressed as a percentage. The ``-m`` flag also shows the line numbers of missing statements:: $ coverage report -m - Name Stmts Exec Cover Missing + Name Stmts Miss Cover Missing ------------------------------------------------------- - my_program 20 16 80% 33-35, 39 - my_module 15 13 86% 8, 12 - my_other_module 56 50 89% 17-23 + my_program 20 4 80% 33-35, 39 + my_module 15 2 86% 8, 12 + my_other_module 56 6 89% 17-23 ------------------------------------------------------- - TOTAL 91 79 87% + TOTAL 91 12 87% You can restrict the report to only certain files by naming them on the command line:: $ coverage report -m my_program.py my_other_module.py - Name Stmts Exec Cover Missing + Name Stmts Miss Cover Missing ------------------------------------------------------- - my_program 20 16 80% 33-35, 39 - my_other_module 56 50 89% 17-23 + my_program 20 4 80% 33-35, 39 + my_other_module 56 6 89% 17-23 ------------------------------------------------------- - TOTAL 76 66 87% + TOTAL 76 10 87% Other common reporting options are described above in :ref:`cmd_reporting`. @@ -267,3 +271,10 @@ Diagnostics ----------- The **debug** command shows internal information to help diagnose problems. +If you are reporting a bug about coverage.py, including the output of this +command can often help:: + + $ coverage debug sys > please_attach_to_bug_report.txt + +Two types of information are available: ``sys`` to show system configuration, +and ``data`` to show a summary of the collected coverage data. diff --git a/doc/index.rst b/doc/index.rst index 8c50983..fa18807 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -23,7 +23,7 @@ Coverage measurement is typically used to gauge the effectiveness of tests. It can show which parts of your product code are being exercised by tests, and which are not. -The latest version is 3.3.1, released 6 March 2010. +The latest version is 3.4, in beta. It is supported on Python 2.3 through 3.1. @@ -32,9 +32,9 @@ Quick start Getting started is easy: -#. Install coverage.py from the `coverage page on the Python Package Index`__, - or by using "easy_install coverage". You may need to install the - python-dev support files, for example with "apt-get install python-dev". +#. Install coverage.py from the `coverage page on the Python Package Index`_, + or by using "easy_install coverage". For a few more details, see + :ref:`install`. #. Use ``coverage run`` to execute your program and gather data: @@ -48,12 +48,12 @@ Getting started is easy: .. code-block:: console $ coverage report -m - Name Stmts Exec Cover Missing + Name Stmts Miss Cover Missing ------------------------------------------------------- - my_program 20 16 80% 33-35, 39 - my_other_module 56 50 89% 17-23 + my_program 20 4 80% 33-35, 39 + my_other_module 56 6 89% 17-23 ------------------------------------------------------- - TOTAL 76 66 87% + TOTAL 76 10 87% #. For a nicer presentation, use ``coverage html`` to get annotated HTML listings detailing missed lines: @@ -63,10 +63,10 @@ Getting started is easy: $ coverage html Then visit htmlcov/index.html in your browser, to see a - `report like this`__. + `report like this`_. -__ http://pypi.python.org/pypi/coverage -__ /code/coverage/sample_html/index.html +.. _coverage page on the Python Package Index: http://pypi.python.org/pypi/coverage +.. _report like this: /code/coverage/sample_html/index.html Using coverage.py @@ -81,7 +81,8 @@ Some test runners provide coverage integration to make it easy to use coverage while running tests. For example, `nose`_ has a `cover plug-in`_. You can fine-tune coverage's view of your code by directing it to ignore parts -that you know aren't interesting. See :ref:`excluding` for details. +that you know aren't interesting. See :ref:`source` and :ref:`excluding` for +details. .. _nose: http://somethingaboutorange.com/mrl/projects/nose .. _cover plug-in: http://somethingaboutorange.com/mrl/projects/nose/0.11.1/plugins/cover.html @@ -105,6 +106,7 @@ More information .. toctree:: :maxdepth: 1 + install cmd config api diff --git a/doc/install.rst b/doc/install.rst new file mode 100644 index 0000000..fe85d37 --- /dev/null +++ b/doc/install.rst @@ -0,0 +1,32 @@ +.. _install: + +============ +Installation +============ + +:history: 20100725T225600, new for 3.4. + +.. _coverage_pypi: http://pypi.python.org/pypi/coverage + +Installing coverage.py is simple: + +#. Download the appropriate kit from the + `coverage page on the Python Package Index`__. + +#. + +.. __: coverage_pypi_ + + +You may need to install the python-dev support files, for example with "apt-get +install python-dev". + + +Installing on Windows +--------------------- + +For Windows, kits are provided on the `PyPI page`__ for each version of Python and architecture +combination. These kits require that setuptools be installed as a pre-requisite, +but otherwise are self-contained. + +.. __: coverage_pypi_ |