# HG changeset patch
# User osimons
# Date 1251935411 0
# Node ID b00da52e942fcdf1bb6f54eef00c625bffde61af
# Parent  8931a5ebdc7abd63905cc59ced45d7a1e734953b
0.6dev: Adding docs for `<python:figleaf>` command. Closes #438.

diff --git a/bitten/build/pythontools.py b/bitten/build/pythontools.py
--- a/bitten/build/pythontools.py
+++ b/bitten/build/pythontools.py
@@ -375,6 +375,14 @@
         log.warning('Error opening coverage summary file (%s)', e)
 
 def figleaf(ctxt, summary=None, include=None, exclude=None):
+    """Extract data from a ``Figleaf`` run.
+    
+    :param ctxt: the build context
+    :type ctxt: `Context`
+    :param summary: path to the file containing the coverage summary
+    :param include: patterns of files or directories to include in the report
+    :param exclude: patterns of files or directories to exclude from the report
+    """
     from figleaf import get_lines
     coverage = xmlio.Fragment()
     try:
diff --git a/doc/commands.txt b/doc/commands.txt
--- a/doc/commands.txt
+++ b/doc/commands.txt
@@ -796,6 +796,43 @@
 
   <python:trace summary="build/trace.out" coverdir="build/coverage" />
 
+
+--------------------
+``<python:figleaf>``
+--------------------
+
+Extracts coverage information recorded by Figleaf_.
+
+.. _figleaf: http://darcs.idyll.org/~t/projects/figleaf/doc/
+
+Parameters
+----------
+
++--------------+-------------------------------------------------------------+
+| Name         | Description                                                 |
++==============+=============================================================+
+| ``summary``  | Path to the summary file written by ``figleaf``,            |
+|              | relative to the project source directory.                   |
++--------------+-------------------------------------------------------------+
+| ``include``  | List of glob patterns (separated by space) that specify     |
+|              | which Python file should be included in the coverage report |
++--------------+-------------------------------------------------------------+
+| ``exclude``  | List of glob patterns (separated by space) that specify     |
+|              | which Python file should be excluded from the coverage      |
+|              | report                                                      |
++--------------+-------------------------------------------------------------+
+
+Examples
+--------
+
+.. code-block:: xml
+
+  <step id="figleaf" description="Figleaf coverage">
+    <sh:exec executable="figleaf" args="setup.py test"/>
+    <python:figleaf summary=".figleaf" exclude="build/* setup* */tests/*"/>
+  </step>
+
+
 -------------------
 ``<python:pylint>``
 -------------------