improve and integrate docs

CHANGELOG

@@ -1,6 +1,13 @@
 2.8.0.dev (compared to 2.7.X)
 -----------------------------
 
+- new ``--lf`` and ``-ff`` options to run only the last failing tests or
+  "failing tests first" from the last run.  This functionality is provided 
+  through porting the formerly external pytest-cache plugin into pytest core.
+  BACKWARD INCOMPAT: if you used pytest-cache's functionality to persist
+  data between test runs be aware that we don't serialize sets anymore.
+  Thanks Ronny Pfannschmidt for most of the merging work.
+
 - "-r" option now accepts "a" to include all possible reports, similar
   to passing "fEsxXw" explicitly (isse960).
   Thanks Abhijeet Kasurde for the PR.
@@ -43,10 +50,6 @@
   files and upwards by default (--confcutdir can still be set to override this).
   Thanks Bruno Oliveira for the PR.
 
-- merge a refined variant of the pytest-cache extension into core
-  it uses json instead of execnet for the serializer
-  and deactivates the external cache plugin
-
 - fix issue768: docstrings found in python modules were not setting up session
   fixtures. Thanks Jason R. Coombs for reporting and Bruno Oliveira for the PR.
 

doc/en/cache.rst

@@ -5,9 +5,10 @@ cache: working with cross-testrun state
 
 .. warning::
 
-  the external pytest-cache plugin used execnet_ as serializer,
+  The functionality of this core plugin was previosuly distributed
-  which supported a wider range of builtin objects.
+  as a third party plugin named ``pytest-cache``.  The core plugin
-  the buitin one however uses json.
+  is compatible regarding command line options and API usage except that you
+  can only store/receive data between test runs that is json-serializable.
 
 Usage
 ---------
@@ -201,8 +202,7 @@ the cache and this will be quick::
 
     test_caching.py:12: AssertionError
 
-Consult the `pytest-cache API <http://packages.python.org/pytest-cache/api.html>`_
+See the `cache-api`_ for more details.
-for more details.
 
 
 Inspecting Cache content
@@ -237,6 +237,8 @@ servers where isolation and correctness is more important
 than speed.
 
 
+.. _`cache-api`:
+
 config.cache API
 ========================================
 

doc/en/contents.rst

@@ -12,6 +12,7 @@ Full pytest documentation
 
    overview
    apiref
+   cache
    plugins
    plugins_index/index
    example/index

doc/en/index.rst

@@ -32,6 +32,7 @@ pytest: helps you write better programs
  - :ref:`skipping` (improved in 2.4)
  - :ref:`distribute tests to multiple CPUs <xdistcpu>` through :ref:`xdist plugin <xdist>`
  - :ref:`continuously re-run failing tests <looponfailing>`
+ - :doc:`cache`
  - flexible :ref:`Python test discovery`
 
 **integrates with other testing methods and tools**: