fix up install docs and plugin docs for the final release

have CHANGELOG be a file containing links instead of a symlink
beause it causes issues with pip-install on some systems.

--HG--
branch : trunk

CHANGELOG

@@ -1 +0,0 @@
-doc/changelog.txt

CHANGELOG

@@ -0,0 +1,7 @@
+
+see doc/announce/release-1.1.0.txt for a summary 
+of the last minor release
+
+and 
+
+see doc/changelog.txt for details

doc/announce/release-1.1.0.txt

@@ -3,30 +3,30 @@ py.test/pylib 1.1.0: Python3, Jython, advanced skipping, cleanups ...
 
 Features:
 
-* compatible to Python3 (single py2/py3 source), works with Distribute
+* compatible to Python3 (single py2/py3 source), `easy to install`_
 * generalized marking_: mark tests one a whole-class or whole-module basis
 * conditional skipping_: skip/xfail based on platform/dependencies
 
 Fixes:
 
 * code reduction and "de-magification" (e.g. 23 KLoc -> 11 KLOC)
-* distribute testing requires the now separately released 'execnet' package 
+* distribute testing requires the now separately released execnet_ package 
 * funcarg-setup/caching, "same-name" test modules now cause an exlicit error
-* de-cluttered reporting, --report option for skipped/xfail details 
+* de-cluttered reporting options, --report for skipped/xfail details 
 
 Compatibilities
 
 1.1.0 should allow running test code that already worked well with 1.0.2 
 plus some more due to improved unittest/nose compatibility.  
 
-More information:
+More information: http://pytest.org 
-
-    http://pytest.org 
 
 thanks and have fun,
 
 holger (http://twitter.com/hpk42)
 
+.. _execnet: http://codespeak.net/execnet
+.. _`easy to install`: ../install.html
 .. _marking: ../test/plugin/mark.html
 .. _skipping: ../test/plugin/skipping.html
 

doc/install.txt

@@ -3,29 +3,77 @@
     Downloading
     ==============
 
-    .. _`PyPI project page`: http://pypi.python.org/pypi/py/
+.. _`PyPI project page`: http://pypi.python.org/pypi/py/
 
-    Latest Release, see `PyPI project page`_
 
-using easy_install (via Distribute or setuptools)
+py.test/pylib compat/install info in a nutshell
 ===================================================
 
-It is recommended to use `Distribute for installation`_ as a drop-in
+PyPI Pyckage name: "**py**", see `PyPI project page`_ for latest version
-replacement for setuptools_. While setuptools should work well on
+
-Python2 versions, `Distribute`_ allows to install py.test on Python3 
+Installers: easy_install_ and pip_, setuptools_ or Distribute_
-and it avoids issue on Windows.  With either packaging system 
+
-you can type::
+Pythons: 2.4, 2.5, 2.6, 3.0, 3.1, Jython-2.5.1, PyPy-1.1
+
+Operating systems: Linux, Windows and OSX + probably many others
+
+
+Best practise: install tool and dependencies virtually
+===========================================================
+
+It is recommended to work with virtual environments 
+(e.g. virtualenv_ or buildout_ based) and use easy_install_
+(or pip_) for installing py.test/pylib and any dependencies 
+you need to run your tests.  Local virtual Python environments 
+(as opposed to system-wide "global" environments) make for a more 
+reproducible and reliable test environment. 
+
+Note: as of November 2009 pytest/pylib 1.1 RPMs and DEB packages 
+are not available.  If you want to easy_install the newest py.test
+and pylib do everyone a favour and uninstall older versions 
+from the global system e.g. like this on Ubuntu::
+
+    sudo apt-get remove --purge python-codespeak-lib
+
+.. _`virtualenv`: http://pypi.python.org/pypi/virtualenv
+.. _`buildout`: http://www.buildout.org/
+.. _pip: http://pypi.python.org/pypi/pip
+.. _`easy_install`:
+
+using easy_install (from setuptools or Distribute)
+===================================================
+
+Both `Distribute`_ and setuptools_ provide the ``easy_install``
+installation tool.  While setuptools should work ok with 
+Python2 interpreters, `Distribute`_ also works with Python3 
+and it avoids some issues on Windows.  In both cases you
+can open a command line window and then type::
 
     easy_install -U py 
 
-to get the latest release of the py lib and py.test.  The ``-U`` switch
+to install the latest release of the py lib and py.test.  The ``-U`` switch
 will trigger an upgrade if you already have an older version installed. 
-On Linux systems you may need to execute the command as superuser and
-on Windows you might need to write down the full path to ``easy_install``. 
 
-The py lib and its tools are expected to work well on Linux,
+If you now type::
-Windows and OSX, Python versions 2.4, 2.5, 2.6 through to
+
-the Python3 versions 3.0 and 3.1 and Jython 
+    py.test --version
+
+you should see the version number and the import location of the tool.
+Maybe you want to head on with the `quickstart`_ now? 
+
+.. _quickstart: test/quickstart.html
+
+Troubleshooting
+========================
+
+**On Linux**: If ``easy_install`` fails because it needs to run
+as the superuser you are trying to install things globally 
+and need to put ``sudo`` in front of the command. 
+
+**On Windows**: If "easy_install" or "py.test" are not found
+please see here: `How do i run a Python program under Windows?`_
+
+.. _`How do i run a Python program under Windows?`: http://www.python.org/doc/faq/windows/#how-do-i-run-a-python-program-under-windows  
 
 .. _mercurial: http://mercurial.selenic.com/wiki/
 .. _`Distribute`: 
@@ -37,9 +85,8 @@ the Python3 versions 3.0 and 3.1 and Jython
 Working from version control or a tarball 
 =================================================
 
-To follow development or help with fixing things
+To follow development or start experiments, checkout the 
-for the next release, checkout the complete code
+complete code and documentation source with mercurial_::
-and documentation source with mercurial_::
 
     hg clone https://bitbucket.org/hpk42/py-trunk/
 
@@ -68,14 +115,14 @@ in order to work inline with the tools and the lib of your checkout.
 
 .. _`directly use a checkout`: 
 
-directly use a checkout or tarball
+directly use a checkout or tarball 
 -------------------------------------------------------------
 
-Once you got yourself a checkout_ or tarball_ you only need to 
+Once you got yourself a checkout_ or tarball_ it is usually a good 
-set ``PYTHONPATH`` and ``PATH`` environment variables. 
+idea to add the parent directory of the ``py`` package directory 
-It is usually a good idea to add the parent directory of the ``py`` package 
+to your ``PYTHONPATH`` and ``py/bin`` or ``py\bin\win32`` to your 
-directory to your ``PYTHONPATH`` and ``py/bin`` or ``py\bin\win32`` to your 
+system wide ``PATH`` settings.  There are helper scripts that 
-system wide ``PATH`` settings.  There are helper scripts that set ``PYTHONPATH`` and ``PATH`` on your system: 
+set ``PYTHONPATH`` and ``PATH`` on your system: 
 
 on windows execute::
 
@@ -90,6 +137,9 @@ on linux/OSX add this to your shell initialization::
 both of which which will get you good settings 
 for ``PYTHONPATH`` and ``PATH``.
 
+If you install ``py.test`` this way you can easily
+``hg pull && hg up`` your checkout to follow the
+development tree.
 
 note: scripts look for "nearby" py-lib 
 -----------------------------------------------------
@@ -104,22 +154,15 @@ for "nearby" py libs, so if you have a layout like this::
     py/ 
 
 issuing ``py.test subpkg1`` will use the py lib
-from that projects root directory.  
+from that projects root directory.   Giving the
+state of Python packaging there can be confusion
+in which case issuing::
+
+    py.test --version
+
+tells you both version and import location of the tool.
 
 .. _`command line scripts`: bin.html
-
-Debian and RPM packages 
-===================================
-
-As of August 2009 pytest/pylib 1.0 RPMs and Debian packages 
-are not available.  You will only find 0.9 versions - 
-on Debian systems look for ``python-codespeak-lib``
-and Dwayne Bailey has put together a Fedora `RPM`_. 
-
-If you can help with providing/upgrading distribution
-packages please use of the contact_ channels in case
-of questions or need for changes. 
-
 .. _contact: contact.html
 
 .. _`RPM`: http://translate.sourceforge.net/releases/testing/fedora/pylib-0.9.2-1.fc9.noarch.rpm

doc/test/plugin/coverage.txt

@@ -1,10 +1,9 @@
-pytest_xmlresult plugin (EXTERNAL)
+pytest_coverage plugin (EXTERNAL)
 ==========================================
 
-This plugin allows to write results in an XML format
+This plugin allows to use Ned's coverage_ package, see
-compatible to CruiseControl_, see here for download:
 
     http://github.com/rozza/py.test-plugins
 
-.. _CruiseControl: http://cruisecontrol.sourceforge.net/
 
+.. _coverage: http://pypi.python.org/pypi/coverage

doc/test/plugin/mark.txt

@@ -70,7 +70,15 @@ The order in which marker functions are called is this::
 
 Later called markers may overwrite previous key-value settings. 
 Positional arguments are all appended to the same 'args' list 
-of the Marker object.
+of the Marker object. 
+
+Using "-k MARKNAME" to select tests
+----------------------------------------------------
+
+You can use the ``-k`` command line option to select
+tests::
+
+    py.test -k webtest  # will only run tests marked as webtest
 
 Start improving this plugin in 30 seconds
 =========================================

doc/test/plugin/skipping.txt

@@ -9,7 +9,7 @@ advanced skipping for python test functions, classes or modules.
 
 With this plugin you can mark test functions for conditional skipping 
 or as "xfail", expected-to-fail.  Skipping a test will avoid running it
-while xfail-marked tests will run and result in an inverted outcome:
+at all while xfail-marked tests will run and result in an inverted outcome:
 a pass becomes a failure and a fail becomes a semi-passing one. 
 
 The need for skipping a test is usually connected to a condition.  
@@ -22,29 +22,37 @@ at the end of a test run.
 
 .. _skipif:
 
-mark a test function to be skipped
+Skipping a single function 
 -------------------------------------------
 
-Here is an example for skipping a test function when
+Here is an example for marking a test function to be skipped
-running on Python3::
+when run on a Python3 interpreter::
 
     @py.test.mark.skipif("sys.version_info >= (3,0)")
     def test_function():
         ...
 
-
 During test function setup the skipif condition is 
 evaluated by calling ``eval(expr, namespace)``.  The namespace
-contains the  ``sys`` and ``os`` modules as well as the 
+contains the  ``sys`` and ``os`` modules and the test 
-test ``config`` object.  The latter allows you to skip based 
+``config`` object.  The latter allows you to skip based 
 on a test configuration value e.g. like this::
 
     @py.test.mark.skipif("not config.getvalue('db')")
     def test_function(...):
         ...
 
+Create a shortcut for your conditional skip decorator 
+at module level like this::
 
-mark many test functions at once 
+    win32only = py.test.mark.skipif("sys.platform != 'win32'")
+
+    @win32only
+    def test_function():
+        ...
+
+
+skip groups of test functions 
 --------------------------------------
 
 As with all metadata function marking you can do it at
@@ -58,11 +66,12 @@ for skipping all methods of a test class based on platform::
             # will not be setup or run under 'win32' platform
             #
 
+The ``pytestmark`` decorator will be applied to each test function.
 
 .. _`whole class- or module level`: mark.html#scoped-marking
 
 
-mark a test function as expected to fail 
+mark a test function as **expected to fail**
 -------------------------------------------------------
 
 You can use the ``xfail`` marker to indicate that you
@@ -79,7 +88,7 @@ when it fails. Instead terminal reporting will list it in the
 Same as with skipif_ you can also selectively expect a failure
 depending on platform::
 
-    @py.test.mark.xfail(if"sys.version_info >= (3,0)")
+    @py.test.mark.xfail("sys.version_info >= (3,0)")
 
     def test_function():
         ...
@@ -89,7 +98,7 @@ skipping on a missing import dependency
 --------------------------------------------------
 
 You can use the following import helper at module level 
-or within a test or setup function.
+or within a test or test setup function::
 
     docutils = py.test.importorskip("docutils")
 

doc/test/plugin/xmlresult.txt

@@ -1,6 +1,9 @@
-pytest_coverage plugin (EXTERNAL)
+pytest_xmlresult plugin (EXTERNAL)
 ==========================================
 
-This plugin allows to use Ned's coverage package, see
+This plugin allows to write results in an XML format
+compatible to CruiseControl_, see here for download:
 
     http://github.com/rozza/py.test-plugins
+
+.. _CruiseControl: http://cruisecontrol.sourceforge.net/

doc/test/quickstart.txt

@@ -7,7 +7,7 @@ Quickstart
 
 .. _here: ../install.html
 
-If you have any ``easy_install`` (otherwise see here_) just type::
+If you have the ``easy_install`` tool (otherwise see here_) just type::
 
     easy_install -U py 
 
@@ -30,7 +30,7 @@ and will see output like this:
 .. sourcecode:: python 
 
     =========================== test session starts ============================
-    python: platform linux2 -- Python 2.6.2
+    python: platform linux2 -- Python 2.6.2 -- pytest-1.1.0
     test object 1: test_sample.py
 
     test_sample.py F
@@ -51,15 +51,18 @@ a progress report and important details of the failure.
 
 **Where to go from here**
 
-`tutorials`_: a collection of starting points with code examples
-
 `features`_: overview and description of test features
 
-`contact`_: many ways for feedback and questions 
+`plugins`_: a list of available plugins which each contain usage examples 
+
+`tutorials`_: some blog entries and starting points with code examples
+
+`contact`_: if you want to feedback or have problems
 
 .. _`contact`: ../contact.html
 .. _`automatically collected`: features.html#autocollect
 .. _install: ../install.html
+.. _plugins: plugin/index.html
 .. _features: features.html
 .. _tutorials: talks.html
 

py/plugin/pytest_mark.py

@@ -65,6 +65,15 @@ The order in which marker functions are called is this::
 Later called markers may overwrite previous key-value settings. 
 Positional arguments are all appended to the same 'args' list 
 of the Marker object. 
+
+Using "-k MARKNAME" to select tests
+----------------------------------------------------
+
+You can use the ``-k`` command line option to select
+tests::
+
+    py.test -k webtest  # will only run tests marked as webtest
+
 """
 import py
 

py/plugin/pytest_skipping.py

@@ -3,7 +3,7 @@ advanced skipping for python test functions, classes or modules.
 
 With this plugin you can mark test functions for conditional skipping 
 or as "xfail", expected-to-fail.  Skipping a test will avoid running it
-while xfail-marked tests will run and result in an inverted outcome:
+at all while xfail-marked tests will run and result in an inverted outcome:
 a pass becomes a failure and a fail becomes a semi-passing one. 
 
 The need for skipping a test is usually connected to a condition.  
@@ -16,29 +16,37 @@ at the end of a test run.
 
 .. _skipif:
 
-mark a test function to be skipped
+Skipping a single function 
 -------------------------------------------
 
-Here is an example for skipping a test function when
+Here is an example for marking a test function to be skipped
-running on Python3::
+when run on a Python3 interpreter::
 
     @py.test.mark.skipif("sys.version_info >= (3,0)")
     def test_function():
         ...
 
-
 During test function setup the skipif condition is 
 evaluated by calling ``eval(expr, namespace)``.  The namespace
-contains the  ``sys`` and ``os`` modules as well as the 
+contains the  ``sys`` and ``os`` modules and the test 
-test ``config`` object.  The latter allows you to skip based 
+``config`` object.  The latter allows you to skip based 
 on a test configuration value e.g. like this::
 
     @py.test.mark.skipif("not config.getvalue('db')")
     def test_function(...):
         ...
 
+Create a shortcut for your conditional skip decorator 
+at module level like this::
 
-mark many test functions at once 
+    win32only = py.test.mark.skipif("sys.platform != 'win32'")
+
+    @win32only
+    def test_function():
+        ...
+
+
+skip groups of test functions 
 --------------------------------------
 
 As with all metadata function marking you can do it at
@@ -52,11 +60,12 @@ for skipping all methods of a test class based on platform::
             # will not be setup or run under 'win32' platform
             #
 
+The ``pytestmark`` decorator will be applied to each test function.
 
 .. _`whole class- or module level`: mark.html#scoped-marking
 
 
-mark a test function as expected to fail 
+mark a test function as **expected to fail**
 -------------------------------------------------------
 
 You can use the ``xfail`` marker to indicate that you
@@ -73,7 +82,7 @@ when it fails. Instead terminal reporting will list it in the
 Same as with skipif_ you can also selectively expect a failure
 depending on platform::
 
-    @py.test.mark.xfail(if"sys.version_info >= (3,0)")
+    @py.test.mark.xfail("sys.version_info >= (3,0)")
 
     def test_function():
         ...