many doc improvements and fixes

doc/en/example/simple.txt

@@ -106,7 +106,7 @@ directory with the above conftest.py::
 
     $ py.test
     =========================== test session starts ============================
-    platform linux2 -- Python 2.7.3 -- pytest-2.3.0.dev20
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.0.dev27
     collected 0 items
     
     =============================  in 0.00 seconds =============================
@@ -150,20 +150,20 @@ and when running it will see a skipped "slow" test::
 
     $ py.test -rs    # "-rs" means report details on the little 's'
     =========================== test session starts ============================
-    platform linux2 -- Python 2.7.3 -- pytest-2.3.0.dev20
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.0.dev27
     collected 2 items
     
     test_module.py .s
     ========================= short test summary info ==========================
-    SKIP [1] /tmp/doc-exec-195/conftest.py:9: need --runslow option to run
+    SKIP [1] /tmp/doc-exec-60/conftest.py:9: need --runslow option to run
     
-    =================== 1 passed, 1 skipped in 0.01 seconds ====================
+    =================== 1 passed, 1 skipped in 0.03 seconds ====================
 
 Or run it including the ``slow`` marked test::
 
     $ py.test --runslow
     =========================== test session starts ============================
-    platform linux2 -- Python 2.7.3 -- pytest-2.3.0.dev20
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.0.dev27
     collected 2 items
     
     test_module.py ..
@@ -253,7 +253,7 @@ which will add the string to the test header accordingly::
 
     $ py.test
     =========================== test session starts ============================
-    platform linux2 -- Python 2.7.3 -- pytest-2.3.0.dev20
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.0.dev27
     project deps: mylib-1.1
     collected 0 items
     
@@ -276,7 +276,7 @@ which will add info only when run with "--v"::
 
     $ py.test -v
     =========================== test session starts ============================
-    platform linux2 -- Python 2.7.3 -- pytest-2.3.0.dev20 -- /home/hpk/p/pytest/.tox/regen/bin/python
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.0.dev27 -- /home/hpk/p/pytest/.tox/regen/bin/python
     info1: did you know that ...
     did you?
     collecting ... collected 0 items
@@ -287,7 +287,7 @@ and nothing when run plainly::
 
     $ py.test
     =========================== test session starts ============================
-    platform linux2 -- Python 2.7.3 -- pytest-2.3.0.dev20
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.0.dev27
     collected 0 items
     
     =============================  in 0.00 seconds =============================
@@ -319,7 +319,7 @@ Now we can profile which test functions execute the slowest::
 
     $ py.test --durations=3
     =========================== test session starts ============================
-    platform linux2 -- Python 2.7.3 -- pytest-2.3.0.dev20
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.0.dev27
     collected 3 items
     
     test_some_are_slow.py ...
@@ -327,5 +327,79 @@ Now we can profile which test functions execute the slowest::
     ========================= slowest 3 test durations =========================
     0.20s call     test_some_are_slow.py::test_funcslow2
     0.10s call     test_some_are_slow.py::test_funcslow1
-    0.00s call     test_some_are_slow.py::test_funcfast
+    0.00s setup    test_some_are_slow.py::test_funcfast
     ========================= 3 passed in 0.31 seconds =========================
+
+incremental testing - test steps
+---------------------------------------------------
+
+.. regendoc:wipe
+
+Sometimes you may have a testing situation which consists of a series
+of test steps.  If one step fails it makes no sense to execute further
+steps as they are all expected to fail anyway and their tracebacks
+add no insight.  Here is a simple ``conftest.py`` file which introduces
+an ``incremental`` marker which is to be used on classes::
+
+    # content of conftest.py
+
+    import pytest
+
+    def pytest_runtest_makereport(item, call):
+        if hasattr(item.markers, "incremental"):
+            if call.excinfo is not None:
+                parent = item.parent
+                parent._previousfailed = item
+
+    def pytest_runtest_setup(item):
+        if hasattr(item.markers, "incremental"):
+            previousfailed = getattr(item.parent, "_previousfailed", None)
+            if previousfailed is not None:
+                pytest.xfail("previous test failed (%s)" %previousfailed.name)
+
+These two hook implementations work together to abort incremental-marked
+tests in a class.  Here is a test module example::
+
+    # content of test_step.py
+
+    import pytest
+
+    @pytest.mark.incremental
+    class TestUserHandling:
+        def test_login(self):
+            pass
+        def test_modification(self):
+            assert 0
+        def test_deletion(self):
+            pass
+
+    def test_normal():
+        pass
+
+If we run this::
+
+    $ py.test -rx
+    =========================== test session starts ============================
+    platform linux2 -- Python 2.7.3 -- pytest-2.3.0.dev27
+    collected 4 items
+    
+    test_step.py .Fx.
+    
+    ================================= FAILURES =================================
+    ____________________ TestUserHandling.test_modification ____________________
+    
+    self = <test_step.TestUserHandling instance at 0x28e1128>
+    
+        def test_modification(self):
+    >       assert 0
+    E       assert 0
+    
+    test_step.py:9: AssertionError
+    ========================= short test summary info ==========================
+    XFAIL test_step.py::TestUserHandling::()::test_deletion
+      reason: previous test failed (test_modification)
+    ============== 1 failed, 2 passed, 1 xfailed in 0.01 seconds ===============
+
+We'll see that ``test_deletion`` was not executed because ``test_modification``
+failed.  It is reported as an "expected failure".
+