add capturelog generated plugin text

--HG--
branch : trunk

doc/test/plugin/capturelog.txt

@@ -0,0 +1,86 @@
+
+capture output of logging module.
+=================================
+
+
+.. contents::
+  :local:
+
+Installation
+------------
+
+You can install the `pytest-capturelog pypi`_ package 
+with pip::
+
+    pip install pytest-capturelog 
+
+or with easy install::
+
+    easy_install pytest-capturelog
+
+.. _`pytest-capturelog pypi`: http://pypi.python.org/pypi/pytest-capturelog/
+
+Usage
+-----
+
+If the plugin is installed log messages are captured by default and for
+each failed test will be shown in the same manner as captured stdout and
+stderr.
+
+Running without options::
+
+    py.test test_capturelog.py
+
+Shows failed tests like so::
+
+    -------------------------- Captured log ---------------------------
+    test_capturelog.py          26 INFO     text going to logger
+    ------------------------- Captured stdout -------------------------
+    text going to stdout
+    ------------------------- Captured stderr -------------------------
+    text going to stderr
+    ==================== 2 failed in 0.02 seconds =====================
+
+By default each captured log message shows the module, line number,
+log level and message.  Showing the exact module and line number is
+useful for testing and debugging.  If desired the log format and date
+format can be specified to anything that the logging module supports.
+
+Running pytest specifying formatting options::
+
+    py.test --log-format="%(asctime)s %(levelname)s %(message)s" --log-date-format="%Y-%m-%d %H:%M:%S" test_capturelog.py
+
+Shows failed tests like so::
+
+    -------------------------- Captured log ---------------------------
+    2010-04-10 14:48:44 INFO text going to logger
+    ------------------------- Captured stdout -------------------------
+    text going to stdout
+    ------------------------- Captured stderr -------------------------
+    text going to stderr
+    ==================== 2 failed in 0.02 seconds =====================
+
+Further it is possible to disable capturing of logs completely with::
+
+    py.test --nocapturelog test_capturelog.py
+
+Shows failed tests in the normal manner as no logs were captured::
+
+    ------------------------- Captured stdout -------------------------
+    text going to stdout
+    ------------------------- Captured stderr -------------------------
+    text going to stderr
+    ==================== 2 failed in 0.02 seconds =====================
+
+command line options
+--------------------
+
+
+``--nocapturelog``
+    disable log capture
+``--log-format=LOG_FORMAT``
+    log format as used by the logging module
+``--log-date-format=LOG_DATE_FORMAT``
+    log date format as used by the logging module
+
+.. include:: links.txt