Lots of doc updates, more to come.

1 files changed, 76 insertions, 0 deletions

diff --git a/doc/source.rst b/doc/source.rst
new file mode 100644
index 0000000..edfc2fc
--- /dev/null
+++ b/doc/source.rst
@@ -0,0 +1,76 @@
+.. _source:
+
+=======================
+Specifying source files
+=======================
+
+:history: 20100725T172000, new in 3.4
+
+
+When coverage.py is running your program and measuring its execution, it needs
+to know what code to measure and what code not to.  Measurement imposes a speed
+penalty, and the collected data must be stored in memory and then on disk.
+More importantly, when reviewing your coverage reports, you don't want to be
+distracted with modules that aren't your concern.
+
+Coverage.py has a number of ways you can focus it in on the code you care
+about.
+
+
+.. _source_execution:
+
+Execution
+---------
+
+When running your code, the ``coverage run`` command will by default measure
+all code, unless it is part of the Python standard library.
+
+You can specify source to measure with the ``--source`` command-line switch,
+or the ``[run] source`` configuration value.  The value is a list of directories
+or package names.  If specified, only source inside these directories or
+packages will be measured.
+
+You can further fine-tune coverage.py's attention with the ``--include`` and
+``--omit`` switches (or ``[run] include`` and ``[run] omit`` configuration
+values). ``--include`` is a list of filename patterns. If specified, only files
+matching those patterns will be measured. ``--omit`` is also a list of filename
+patterns, specifying files not to measure.  If both ``include`` and ``omit``
+are specified, first the set of files is reduced to only those that match the
+include patterns, then any files that match the omit pattern are removed from
+the set.
+
+The ``include`` and ``omit`` filename patterns follow typical shell syntax:
+``*`` matches any number of characters and ``?`` matches a single character.
+The full semantics are specified in the `fnmatch docs`_.
+
+.. _fnmatch docs: http://docs.python.org/library/fnmatch.html
+
+The ``source``, ``include``, and ``omit`` values all work together to determine
+the source that will be measured.
+
+
+.. _source_reporting:
+
+Reporting
+---------
+
+Once your program is measured, you can specify the source files you want
+reported.  Usually you want to see all the code that was measured, but if you
+are measuring a large project, you may want to get reports for just certain
+parts.
+
+The report commands (``report``, ``html``, ``annotate``, and ``xml``) all take
+optional ``modules`` arguments, and ``--include`` and ``--omit`` switches. The
+``modules`` arguments specify particular modules to report on.  The ``include``
+and ``omit`` values are lists of filename patterns, just as with the ``run``
+command.
+
+Remember that the reporting commands can only report on the data that has been
+collected, so the data you're looking for may not be in the data available for
+reporting.
+
+Note that these are ways of specifying files to measure.  You can also exclude
+individual source lines.  See :ref:`Excluding code from coverage <excluding>`
+for details.
+
+