Documentation polishing for a 3.1 release.

6 files changed, 74 insertions, 18 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index bad54619..4104672f 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -20,8 +20,8 @@ Version 3.1b1, 27 September 2009
   syntax is still supported.  Try "coverage help" to see the new commands.

   Thanks to Ben Finney for early help.

 

-- Added the "coverage xml" command for producing coverage reports in a

-  Cobertura-compatible XML format.  Thanks, Bill Hart.

+- Added an experimental "coverage xml" command for producing coverage reports

+  in a Cobertura-compatible XML format.  Thanks, Bill Hart.

 

 - Added the --timid option to enable a simpler slower trace function that works

   for DecoratorTools projects, including TurboGears.  Fixed `issue 12`_ and

diff --git a/TODO.txt b/TODO.txt
index 64076924..5a086339 100644
--- a/TODO.txt
+++ b/TODO.txt
@@ -183,6 +183,7 @@ x Tests about the "import __main__" in cmdline.py
     - 3.1a1, 3.1b1, 3.1c1, 3.1

 - Update CHANGES, including release date.

 - Update docs

+    - Version, date, and changes in doc/changes.rst

     - Generate new sample_html to get the latest, incl footer version number:

         cd C:\ned\cog\trunk

         rmdir/s/q htmlcov

diff --git a/doc/changes.rst b/doc/changes.rst
index 8f09dcd6..e540c873 100644
--- a/doc/changes.rst
+++ b/doc/changes.rst
@@ -3,6 +3,7 @@
 :history: 20090524T134300, brand new docs.

 :history: 20090613T164000, final touches for 3.0

 :history: 20090706T205000, changes for 3.0.1

+:history: 20091004T170700, changes for 3.1

 

 ------------------------------------

 Major change history for coverage.py

@@ -13,6 +14,32 @@ see the `CHANGES.txt <http://bitbucket.org/ned/coveragepy/src/tip/CHANGES.txt>`_
 file.

 

 

+Version 3.1, when??

+-------------------

+

+- Python 3.1 is now supported.

+

+- Coverage.py has a new command line syntax with sub-commands.  This expands

+  the possibilities for adding features and options in the future.  The old

+  syntax is still supported.  Try "coverage help" to see the new commands.

+  Thanks to Ben Finney for early help.

+

+- Added an experimental "coverage xml" command for producing coverage reports

+  in a Cobertura-compatible XML format.  Thanks, Bill Hart.

+

+- Added the ``--timid`` option to enable a simpler slower trace function that

+  works for DecoratorTools projects, including TurboGears.  Fixed `issue 12`_

+  and `issue 13`_.

+

+- HTML reports now display syntax-colored Python source.

+

+- Added a "coverage debug" command for getting diagnostic information about the

+  coverage.py installation.

+

+.. _issue 12: http://bitbucket.org/ned/coveragepy/issue/12

+.. _issue 13: http://bitbucket.org/ned/coveragepy/issue/13

+

+

 Version 3.0.1, 7 July 2009

 --------------------------

 

diff --git a/doc/cmd.rst b/doc/cmd.rst
index 3a3451af..9c0d4119 100644
--- a/doc/cmd.rst
+++ b/doc/cmd.rst
@@ -7,6 +7,7 @@ Coverage command line usage
 :history: 20090524T134300, brand new docs.
 :history: 20090613T164000, final touches for 3.0
 :history: 20090913T084400, new command line syntax
+:history: 20091004T170700, changes for 3.1
 
 .. highlight:: console
 
@@ -26,6 +27,10 @@ determine the action performed:
 
 * **annotate** -- Annotate source files with coverage results.
 
+* **debug** -- Get diagnostic information.
+
+Help is available with ``coverage help``, or with the ``--help`` switch on any
+other command.
 
 
 Execution
@@ -44,19 +49,19 @@ By default, coverage does not measure code installed with the Python interpreter
 If you want to measure that code as well as your own, add the ``-L`` flag.
 
 If your coverage results seems to be overlooking code that you know has been
-executed, try running coverage again with the ``--timid`` flag.  This uses a simpler
-but slower trace method.  Projects that use DecoratorTools, including TurboGears,
-will need to use ``--timid`` to get correct results.  This option can also be set
-with the environment variable COVERAGE_OPTIONS set to ``--timid``.
-
+executed, try running coverage again with the ``--timid`` flag.  This uses a
+simpler but slower trace method. Projects that use DecoratorTools, including
+TurboGears, will need to use ``--timid`` to get correct results.  This option
+can also be enabled by setting the environment variable COVERAGE_OPTIONS to
+``--timid``.
 
 
 Data file
 ---------
 
-Coverage collects execution data in a file called ".coverage".  If need be, you can
-set a new file name with the COVERAGE_FILE environment variable.  By default,
-each run of your program starts with an empty data set.  If you need to run your
+Coverage collects execution data in a file called ".coverage".  If need be, you
+can set a new file name with the COVERAGE_FILE environment variable.  By default,
+each run of your program starts with an empty data set. If you need to run your
 program multiple times to get complete data (for example, because you need to
 supply disjoint options), you can accumulate data across runs with the ``-a``
 flag on the **run** command.  
@@ -121,10 +126,10 @@ command line::
     -------------------------------------------------------
     TOTAL                        76     66    87%
 
-The ``-o`` flag omits files that begin with specified prefixes. For example, this
-will omit any modules in the django directory::
+The ``--omit`` flag omits files that begin with specified prefixes. For example,
+this will omit any modules in the django directory::
 
-    $ coverage report -m -o django
+    $ coverage report -m --omit django
 
 
 
@@ -142,7 +147,7 @@ Lines are highlighted green for executed, red for missing, and gray for
 excluded.  The counts at the top of the file are buttons to turn on and off
 the highlighting.
 
-The ``-d`` argument to specify an output directory is required::
+The ``-d`` argument specifies an output directory, and is required::
 
     $ coverage html -d covhtml
 
@@ -174,3 +179,16 @@ For example::
     >     else:
     >         a = 2
   
+
+XML reporting
+-------------
+
+The **xml** command writes coverage data to a "coverage.xml" file in a format
+compatible with `Cobertura <http://cobertura.sourceforge.net>`_.  This command
+is still experimental.  I need feedback from users to finish it up.
+
+
+Diagnostics
+-----------
+
+The **debug** command shows internal information to help diagnose problems.
diff --git a/doc/faq.rst b/doc/faq.rst
index 385f1fec..6b8e7fa7 100644
--- a/doc/faq.rst
+++ b/doc/faq.rst
@@ -10,6 +10,16 @@ Frequently asked questions
 --------------------------
 
 
+**Q: I use `nose`_ to run my tests, and the ``--with-cover`` plugin doesn't let
+me create HTML or XML reports.  What should I do?
+
+.. _nose: http://somethingaboutorange.com/mrl/projects/nose
+
+First run your tests and collect coverage data with nose and its plugin.  This
+will write coverage data into a .coverage file.  Then run coverage.py from the
+command line to create the reports you need from that data.
+
+
 **Q: Why do unexecutable lines show up as executed?**
 
 Usually this is because you've updated your code and run coverage on it
@@ -36,9 +46,9 @@ If you are using the :ref:`API <api>`, you need to call coverage.start() before
 importing the modules that define your functions.
 
 
-**Q: Does coverage work on Python 3.x?**
+**Q: Does coverage.py work on Python 3.x?**
 
-Not yet, but that's next on my list.
+Yes, as of coverage.py 3.1, Python 3.1 is supported.
 
 
 **Q: Isn't coverage testing the best thing ever?**
diff --git a/doc/index.rst b/doc/index.rst
index 884a2558..c18cf1ce 100644
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -17,8 +17,8 @@ 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.0.1, released 7 July 2009.  It is supported on Python

-2.3 through 2.6.

+The latest version is 3.1, released ??WHEN??.  It is supported on Python

+2.3 through 3.1.

 

 

 Quick start