various documentation related refinements

--HG--
branch : trunk

Author: hpk42

doc/apiref.txt

@@ -9,9 +9,12 @@ py.test reference documentation
    xunit_setup.txt
    capture.txt
    monkeypatch.txt
+   tmpdir.txt
    skipping.txt
    mark.txt
-   doctest.txt
    recwarn.txt
    reporting.txt
+   debugging.txt
+   doctest.txt
+   unittest.txt
 

doc/capture.txt

@@ -1,4 +1,6 @@
 
+.. _`captures`:
+
 Capturing of stdout/stderr output
 =========================================================
 
@@ -25,6 +27,7 @@ There are two ways in which ``py.test`` can perform capturing:
   output from code like ``sys.stderr.write(...)`` will be captured with 
   this method.
 
+.. _`disable capturing`:
 
 You can influence output capturing mechanisms from the command line::
 

doc/customize.txt

@@ -5,7 +5,7 @@ Customizing and Extending py.test
 basic test configuration
 ===================================
 
-available command line options
+Command line options
 ---------------------------------
 
 You can see command line options by running::
@@ -26,10 +26,6 @@ allow to:
 
 * `set option defaults`_
 
-* `implement hooks`_
-
-* `specify funcargs`_
-
 or set particular variables to influence the testing process:
 
 * ``pytest_plugins``: list of named plugins to load
@@ -68,25 +64,6 @@ To find out about the particular switches and type::
 This will print information about all options in your
 environment, including your local plugins.
 
-.. _`basetemp`:
-
-Temporary directories
--------------------------------------------
-
-You can create directories by calling one of two methods
-on the config object:
-
-- ``config.mktemp(basename)``: create and return a new tempdir
-
-- ``config.ensuretemp(basename)``: create or return a new tempdir
-
-temporary directories are created as sub directories of a per-session
-testdir and will keep around the directories of the last three test
-runs.  You can set the base temporary directory through the command line
-`--basetemp`` option.  When distributing tests on the same machine,
-``py.test`` takes care to configure a basetemp directory for the sub
-processes such that all temporary data lands below below a single
-per-test run basetemp directory.
 
 .. _`function arguments`: funcargs.html
 .. _`extensions`:
@@ -226,7 +203,6 @@ If you want to look at the names of existing plugins, use
 the ``--traceconfig`` option.
 
 .. _`well specified hooks`:
-.. _`implement hooks`:
 
 py.test hook reference
 ====================================
@@ -361,17 +337,21 @@ name.  Given a filesystem ``fspath`` it is constructed as follows:
 
 * import the root package as ``root``
 
-Complete reference of objects involved in hooks
+Reference of important objects involved in hooks
 ===========================================================
 
-.. autoclass:: pytest.plugin.runner.CallInfo
+.. autoclass:: pytest._config.Config
     :members:
 
-.. autoclass:: pytest.plugin.runner.TestReport
-    :members:
+.. autoclass:: pytest.collect.Item
+    :inherited-members:
 
 .. autoclass:: pytest.collect.Node
     :members:
 
-.. autoclass:: pytest.collect.Item
-    :inherited-members:
+.. autoclass:: pytest.plugin.runner.CallInfo
+    :members:
+
+.. autoclass:: pytest.plugin.runner.TestReport
+    :members:
+

doc/debugging.txt

@@ -0,0 +1,59 @@
+
+Tracebacks and debugging Python failures
+=================================================================
+
+Stopping after the first (or N) failures
+----------------------------------------------------
+
+To stop the testing process after the first (N) failures::
+
+    py.test -x            # stop after first failure
+    py.test -maxfail=2    # stop after two failures
+
+Modifying traceback printing
+----------------------------------------------------
+
+Examples for modifying traceback printing::
+
+    py.test --showlocals # show local variables in tracebacks
+    py.test -l           # show local variables (shortcut)
+
+    py.test --tb=long    # the default informative traceback formatting
+    py.test --tb=native  # the Python standard library formatting
+    py.test --tb=short   # a shorter traceback format
+    py.test --tb=line    # only one line per failure
+
+Dropping to PDB (Python Debugger) on failures
+----------------------------------------------------
+
+.. _PDB: http://docs.python.org/library/pdb.html
+
+Python comes with a builtin Python debugger called PDB_.  ``py.test`` 
+allows to drop into the PDB prompt via a command line option::
+
+    py.test --pdb
+
+This will invoke the Python debugger on every failure.  Often you might
+only want to do this for the first failing test to understand a certain
+failure situation::
+
+    py.test -x --pdb   # drop to PDB on first failure, then end test session
+    py.test --pdb --maxfail=3  # drop to PDB for the first three failures
+
+
+Setting a breakpoint / aka ``set_trace()``
+----------------------------------------------------
+
+If you want to set a breakpoint and enter the ``pdb.set_trace()`` you
+can use a helper::
+
+    def test_function():
+        ...
+        py.test.set_trace()    # invoke PDB debugger and tracing
+
+.. versionadded: 2.0.0
+
+In previous versions you could only enter PDB tracing if
+you :ref:`disable capturing`.
+
+

doc/doctest.txt

@@ -43,12 +43,12 @@ and another like this::
 then you can just invoke ``py.test`` without command line options::
 
     $ py.test
-    ============================= test session starts ==============================
+    =========================== test session starts ============================
     platform linux2 -- Python 2.6.5 -- pytest-2.0.0dev0
-    test path 1: /tmp/doc-exec-224
+    test path 1: /tmp/doc-exec-288
 
     conftest.py .
     example.rst .
     mymodule.py .
 
-    =========================== 3 passed in 0.01 seconds ===========================
+    ========================= 3 passed in 0.01 seconds =========================

doc/example/test_collectonly.py

@@ -5,7 +5,7 @@ def test_function():
     pass
 
 class TestClass:
-    def test_method():
+    def test_method(self):
         pass
-    def test_anothermethod():
+    def test_anothermethod(self):
         pass

doc/funcargs.txt

@@ -31,14 +31,14 @@ into a test module::
 Running the test looks like this::
 
     $ py.test test_simplefactory.py
-    ============================= test session starts ==============================
+    =========================== test session starts ============================
     platform linux2 -- Python 2.6.5 -- pytest-2.0.0dev0
     test path 1: test_simplefactory.py
 
     test_simplefactory.py F
 
-    =================================== FAILURES ===================================
-    ________________________________ test_function _________________________________
+    ================================= FAILURES =================================
+    ______________________________ test_function _______________________________
 
     myfuncarg = 42
 
@@ -47,7 +47,7 @@ Running the test looks like this::
     E       assert 42 == 17
 
     test_simplefactory.py:5: AssertionError
-    =========================== 1 failed in 0.02 seconds ===========================
+    ========================= 1 failed in 0.02 seconds =========================
 
 This means that the test function was called with a ``myfuncarg`` value
 of ``42`` and the assert fails accordingly.  Here is how py.test
@@ -129,7 +129,7 @@ Basic generated test example
 
 Let's consider this test module::
 
-    # content of ./test_example.py
+    # content of test_example.py
     def pytest_generate_tests(metafunc):
         if "numiter" in metafunc.funcargnames:
             for i in range(10):
@@ -141,14 +141,14 @@ Let's consider this test module::
 Running this::
 
     $ py.test test_example.py
-    ============================= test session starts ==============================
+    =========================== test session starts ============================
     platform linux2 -- Python 2.6.5 -- pytest-2.0.0dev0
     test path 1: test_example.py
 
     test_example.py .........F
 
-    =================================== FAILURES ===================================
-    _________________________________ test_func[9] _________________________________
+    ================================= FAILURES =================================
+    _______________________________ test_func[9] _______________________________
 
     numiter = 9
 
@@ -157,7 +157,7 @@ Running this::
     E       assert 9 < 9
 
     test_example.py:7: AssertionError
-    ====================== 1 failed, 9 passed in 0.04 seconds ======================
+    ==================== 1 failed, 9 passed in 0.04 seconds ====================
 
 Here is what happens in detail:
 

doc/monkeypatch.txt

@@ -38,11 +38,11 @@ will be undone.
 
 .. background check:
    $ py.test
-   ============================= test session starts ==============================
+   =========================== test session starts ============================
    platform linux2 -- Python 2.6.5 -- pytest-2.0.0dev0
-   test path 1: /tmp/doc-exec-232
+   test path 1: /tmp/doc-exec-296
 
-   ===============================  in 0.00 seconds ===============================
+   =============================  in 0.00 seconds =============================
 
 Method reference of the monkeypatch function argument
 -----------------------------------------------------