Finish up the docs.

1 files changed, 66 insertions, 0 deletions

diff --git a/doc/excluding.rst b/doc/excluding.rst
new file mode 100644
index 0000000..d336813
--- /dev/null
+++ b/doc/excluding.rst
@@ -0,0 +1,66 @@
+.. _excluding:
+
+============================
+Excluding code from coverage
+============================
+
+:history: 20090613T090500, brand new docs.
+
+You may have code in your project that you know won't be executed, and you want
+to tell coverage to ignore it.  For example, you may have debugging-only code
+that won't be executed during your unit tests. You can tell coverage to exclude
+this code during reporting so that it doesn't clutter your reports with noise
+about code that you don't need to hear about.
+
+Coverage will look for comments marking clauses for exclusion.  In this code,
+the "if debug" clause is excluded from reporting::
+
+    a = my_function1()
+    if debug:   # pragma: no cover
+        msg = "blah blah"
+        log_message(msg, a)
+    b = my_function2()
+        
+Any line with a comment of "pragma: no cover" is excluded.  If that line
+introduces a clause, for example, an if clause, or a function or class
+definition, then the entire clause is also excluded.  Here the __repr__
+function is not reported as missing::
+
+    class MyObject(object):
+        def __init__(self):
+            blah1()
+            blah2()
+            
+        def __repr__(self): # pragma: no cover
+            return "<MyObject>"
+
+Excluded code is executed as usual, and its execution is recorded in the
+coverage data as usual. When producing reports though, coverage excludes it from
+the list of missing code.
+
+
+Advanced exclusion
+------------------
+
+Coverage identifies exclusions by matching lines against a list of regular
+expressions.  Using the coverage :ref:`API <api>`, you can add to that list.
+This is useful if you have often-used constructs to exclude that can be matched
+with a regex. You can exclude them all at once without littering your code with
+exclusion pragmas.
+
+For example, you might decide that __repr__ functions are usually only used
+in debugging code, and are uninteresting to test themselves.  You could exclude
+all of them by adding a regex to the exclusion list::
+
+    coverage.exclude("def __repr__")
+    
+Here's a list of exclusions I've used::
+
+    coverage.exclude('def __repr__')
+    coverage.exclude('if self.debug:')
+    coverage.exclude('if settings.DEBUG')
+    coverage.exclude('raise AssertionError')
+    coverage.exclude('raise NotImplementedError')
+    coverage.exclude('if 0:')
+    coverage.exclude('if __name__ == .__main__.:')
+