update plugin docs, restructure release announcement a bit

--HG--
branch : trunk

doc/announce/release-1.3.1.txt

@@ -1,19 +1,23 @@
 py.test/pylib 1.3.1: new py.test.xfail, --maxfail, better reporting
 ===========================================================================
 
-The 1.3.1 release introduces a new imperative way to "xfail" a test 
+The pylib/py.test 1.3.1 release brings: 
-and a new option --maxfail=NUM to limit the number of executed tests
+
-in case of failures.  This backward-compatible release also brings shorter, 
+- the new imperative ``py.test.xfail()`` helper in order to have a test or 
-more concise tracebacks in several cases.  The underlying code has been 
+  setup function result in an "expected failure"
-simplified and now is compatible to Jython and PyPy, along with some bug 
+- a new option ``--maxfail=NUM`` to stop the test run after some failures
-fixes and refinemnts that have been applied to CPython's code base. 
+- markers/decorators are now applicable to test classes (>=Python2.6)
-If you used older versions of py.test you should be able to upgrade 
+- improved reporting, shorter tracebacks in several cases
-to 1.3.1 without changes to your test source code.  
+- some simplified internals, more compatibility with Jython and PyPy 
+- bug fixes and various refinements
 
 See the below CHANGELOG entry below for more details and
 http://pylib.org/install.html for installation instructions. 
 
-py.test is an advanced automated testing tool working with Python2,
+If you used older versions of py.test you should be able to upgrade 
+to 1.3.1 without changes to your test source code.  
+
+py.test is an automated testing tool working with Python2,
 Python3, Jython and PyPy versions on all major operating systems.  It
 offers a no-boilerplate testing approach and has inspired other testing
 tools and enhancements in the standard Python library for more than five

doc/test/plugin/links.txt

@@ -1,46 +1,46 @@
 .. _`helpconfig`: helpconfig.html
-.. _`pytest_recwarn.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.0/py/_plugin/pytest_recwarn.py
+.. _`pytest_recwarn.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.1/py/_plugin/pytest_recwarn.py
 .. _`unittest`: unittest.html
-.. _`pytest_monkeypatch.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.0/py/_plugin/pytest_monkeypatch.py
+.. _`pytest_monkeypatch.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.1/py/_plugin/pytest_monkeypatch.py
-.. _`pytest_genscript.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.0/py/_plugin/pytest_genscript.py
+.. _`pytest_genscript.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.1/py/_plugin/pytest_genscript.py
 .. _`pastebin`: pastebin.html
 .. _`skipping`: skipping.html
 .. _`genscript`: genscript.html
 .. _`plugins`: index.html
 .. _`mark`: mark.html
 .. _`tmpdir`: tmpdir.html
-.. _`pytest_doctest.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.0/py/_plugin/pytest_doctest.py
+.. _`pytest_doctest.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.1/py/_plugin/pytest_doctest.py
 .. _`capture`: capture.html
-.. _`pytest_nose.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.0/py/_plugin/pytest_nose.py
+.. _`pytest_nose.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.1/py/_plugin/pytest_nose.py
-.. _`pytest_restdoc.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.0/py/_plugin/pytest_restdoc.py
+.. _`pytest_restdoc.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.1/py/_plugin/pytest_restdoc.py
 .. _`restdoc`: restdoc.html
 .. _`xdist`: xdist.html
-.. _`pytest_pastebin.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.0/py/_plugin/pytest_pastebin.py
+.. _`pytest_pastebin.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.1/py/_plugin/pytest_pastebin.py
-.. _`pytest_tmpdir.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.0/py/_plugin/pytest_tmpdir.py
+.. _`pytest_tmpdir.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.1/py/_plugin/pytest_tmpdir.py
 .. _`terminal`: terminal.html
-.. _`pytest_hooklog.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.0/py/_plugin/pytest_hooklog.py
+.. _`pytest_hooklog.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.1/py/_plugin/pytest_hooklog.py
 .. _`capturelog`: capturelog.html
 .. _`junitxml`: junitxml.html
-.. _`pytest_skipping.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.0/py/_plugin/pytest_skipping.py
+.. _`pytest_skipping.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.1/py/_plugin/pytest_skipping.py
 .. _`checkout the py.test development version`: ../../install.html#checkout
-.. _`pytest_helpconfig.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.0/py/_plugin/pytest_helpconfig.py
+.. _`pytest_helpconfig.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.1/py/_plugin/pytest_helpconfig.py
 .. _`oejskit`: oejskit.html
 .. _`doctest`: doctest.html
-.. _`pytest_mark.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.0/py/_plugin/pytest_mark.py
+.. _`pytest_mark.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.1/py/_plugin/pytest_mark.py
 .. _`get in contact`: ../../contact.html
-.. _`pytest_capture.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.0/py/_plugin/pytest_capture.py
+.. _`pytest_capture.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.1/py/_plugin/pytest_capture.py
 .. _`figleaf`: figleaf.html
 .. _`customize`: ../customize.html
 .. _`hooklog`: hooklog.html
-.. _`pytest_terminal.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.0/py/_plugin/pytest_terminal.py
+.. _`pytest_terminal.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.1/py/_plugin/pytest_terminal.py
 .. _`recwarn`: recwarn.html
-.. _`pytest_pdb.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.0/py/_plugin/pytest_pdb.py
+.. _`pytest_pdb.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.1/py/_plugin/pytest_pdb.py
 .. _`monkeypatch`: monkeypatch.html
 .. _`coverage`: coverage.html
 .. _`resultlog`: resultlog.html
-.. _`pytest_junitxml.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.0/py/_plugin/pytest_junitxml.py
+.. _`pytest_junitxml.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.1/py/_plugin/pytest_junitxml.py
 .. _`django`: django.html
-.. _`pytest_unittest.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.0/py/_plugin/pytest_unittest.py
+.. _`pytest_unittest.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.1/py/_plugin/pytest_unittest.py
 .. _`nose`: nose.html
-.. _`pytest_resultlog.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.0/py/_plugin/pytest_resultlog.py
+.. _`pytest_resultlog.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.3.1/py/_plugin/pytest_resultlog.py
 .. _`pdb`: pdb.html

doc/test/plugin/mark.txt

@@ -49,11 +49,13 @@ with classes to apply markers to all its test methods::
     class TestClass:
         def test_startup(self):
             ...
+        def test_startup_and_more(self):
+            ...
 
 This is equivalent to directly applying the decorator to the
-``test_startup`` function. 
+two test functions. 
 
-To remain compatible with Python2.5 you can instead set a 
+To remain compatible with Python2.5 you can also set a 
 ``pytestmark`` attribute on a TestClass like this::
 
     import py
@@ -61,7 +63,7 @@ To remain compatible with Python2.5 you can instead set a
     class TestClass:
         pytestmark = py.test.mark.webtest
 
-or if you need to use multiple markers::
+or if you need to use multiple markers you can use a list::
 
     import py
 
@@ -73,7 +75,7 @@ You can also set a module level marker::
     import py
     pytestmark = py.test.mark.webtest
 
-in which case then it will be applied to all functions and 
+in which case it will be applied to all functions and 
 methods defined in the module.  
 
 Using "-k MARKNAME" to select tests

doc/test/plugin/skipping.txt

@@ -65,8 +65,8 @@ for skipping all methods of a test class based on platform::
             #
 
 The ``pytestmark`` decorator will be applied to each test function.
-If your code targets python2.6 or above you can also use the
+If your code targets python2.6 or above you can equivalently use 
-skipif decorator with classes::
+the skipif decorator on classes::
 
     @py.test.mark.skipif("sys.platform == 'win32'")
     class TestPosixCalls:
@@ -75,8 +75,9 @@ skipif decorator with classes::
             # will not be setup or run under 'win32' platform
             #
 
-It is fine in both situations to use multiple "skipif" decorators
+It is fine in general to apply multiple "skipif" decorators
-on a single function. 
+on a single function - this means that if any of the conditions
+apply the function will be skipped. 
 
 .. _`whole class- or module level`: mark.html#scoped-marking
 
@@ -110,6 +111,17 @@ To specify an explicit reason to be shown with xfailure detail::
 
     @py.test.mark.xfail(..., reason="my reason")
 
+imperative xfail from within a test or setup function
+------------------------------------------------------
+
+If you cannot declare xfail-conditions at import time
+you can also imperatively produce an XFail-outcome from 
+within test or setup code.  Example::
+
+    def test_function():
+        if not valid_config():
+            py.test.xfail("unsuppored configuration")
+
 
 skipping on a missing import dependency
 --------------------------------------------------