added a pytest_helpconfig plugin which groups --version and the new "--help-config" option. rename options and configuration names. streamlines docs.

--HG--
branch : 1.0.x

doc/test/customize.txt

@@ -17,85 +17,80 @@ You can see command line options by running::
     py.test -h 
 
 This will display all available command line options
-including the ones added by plugins `loaded at tool startup`_. 
-
+in your specific environment. 
 
 .. _`project-specific test configuration`: 
 .. _`collect_ignore`: 
 
-conftest.py: project specific test configuration
+conftest.py: project specific hooks and configuration
 --------------------------------------------------------
 
 A unique feature of py.test are its ``conftest.py`` files which
-allow to `set option defaults`_, `implement hooks`_, `specify funcargs`_
+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 
 
-* ``collect_ignore``: list of paths to ignore during test collection (relative to the containing
-  ``conftest.py`` file) 
+* ``collect_ignore``: list of paths to ignore during test collection, relative to the containing ``conftest.py`` file 
 
 * ``rsyncdirs``: list of to-be-rsynced directories for distributed
-  testing 
+  testing, relative to the containing ``conftest.py`` file. 
 
 You may put a conftest.py files in your project root directory or into
 your package directory if you want to add project-specific test options. 
 
 ``py.test`` loads all ``conftest.py`` files upwards from the command
-line specified test files.  It will lookup configuration values
+line file arguments.  It usually looks up configuration values
 right-to-left, i.e. the closer conftest files will be checked first.
-You may have a ``conftest.py`` in your very home directory to have some
-global configuration values. 
-
-There is a flag that may help you debugging your conftest.py 
-configuration::
-
-    py.test --traceconfig 
+This means you can have a ``conftest.py`` in your very home directory to
+have some global configuration values. 
 
 .. _`specify funcargs`: funcargs.html#application-setup-tutorial-example
 
 .. _`set option defaults`: 
 
-setting option defaults 
--------------------------------
+setting persistent option defaults  
+------------------------------------
 
-py.test will lookup values of options in this order:
+py.test will lookup option values in this order: 
 
-* option value supplied at command line 
-* content of environment variable ``PYTEST_OPTION_NAME=...``
-* ``name = ...`` setting in the nearest ``conftest.py`` file.
+* command line
+* conftest.py files 
+* environment variables
 
-The name of an option usually is the one you find 
-in the longform of the option, i.e. the name 
-behind the ``--`` double-dash that you get with ``py.test -h``.
+To find out about the particular switches and type::
 
-IOW, you can set default values for options per project, per
-home-directoray, per shell session or per test-run. 
+    py.test --help-config
+
+This will print information about all options in your
+environment, including your local plugins. 
 
 .. _`basetemp`: 
 
 Temporary directories 
 -------------------------------------------
 
-``py.test`` runs provide means to create per-test session
-temporary (sub) directories through the config object.  
-You can create directories by calling a method
+You can create directories by calling one of two methods
 on the config object: 
 
-- ``config.mktemp(basename)``: create and returns a new tempdir 
+- ``config.mktemp(basename)``: create and return a new tempdir 
 
 - ``config.ensuretemp(basename)``: create or return a new tempdir 
 
-tempdirs are created as sub directories of a per-session testdir 
-and will keep around the directories of the last three 
-test runs.  You can also set the base temporary directory 
-with the `--basetemp`` option.  When distributing 
-tests on the same machine, ``py.test`` takes care to 
-pass around the basetemp directory such that all temporary
-files land below the same basetemp directory.  
-
-The config object is available when implementing `function arguments`_ 
-or `extensions`_ and can otherwise be globally accessed as ``py.test.config``. 
+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`: 

doc/test/plugin/capture.txt

@@ -38,7 +38,7 @@ You can influence output capturing mechanisms from the command line::
 If you set capturing values in a conftest file like this::
 
     # conftest.py
-    conf_capture = 'fd'
+    option_capture = 'fd'
 
 then all tests in that directory will execute with "fd" style capturing. 
 

doc/test/plugin/helpconfig.txt

@@ -0,0 +1,31 @@
+
+pytest_helpconfig plugin
+========================
+
+provide version info, conftest/environment config names.
+
+.. contents::
+  :local:
+
+
+
+command line options
+--------------------
+
+
+``--help-config``
+    show available conftest.py and ENV-variable names.
+``--version``
+    display py lib version and import information.
+
+Start improving this plugin in 30 seconds
+=========================================
+
+
+1. Download `pytest_helpconfig.py`_ plugin source code 
+2. put it somewhere as ``pytest_helpconfig.py`` into your import path 
+3. a subsequent ``py.test`` run will use your local version
+
+Checkout customize_, other plugins_ or `get in contact`_. 
+
+.. include:: links.txt

doc/test/plugin/index.txt

@@ -1,6 +1,6 @@
 
-Plugins related to Python test functions and programs
-=====================================================
+plugins for Python test functions
+=================================
 
 xfail_ mark python test functions as expected-to-fail and report them separately.
 
@@ -13,7 +13,7 @@ capture_ configurable per-test stdout/stderr capturing mechanisms.
 recwarn_ helpers for asserting deprecation and other warnings.
 
 
-Plugins for other testing styles and languages
+plugins for other testing styles and languages
 ==============================================
 
 oejskit_ run javascript tests in real life browsers
@@ -27,7 +27,7 @@ doctest_ collect and execute doctests from modules and test files.
 restdoc_ perform ReST syntax, local and remote reference tests on .rst/.txt files.
 
 
-Plugins for generic reporting and failure logging
+plugins for generic reporting and failure logging
 =================================================
 
 pastebin_ submit failure or test session information to a pastebin service.
@@ -37,8 +37,20 @@ resultlog_ resultlog plugin for machine-readable logging of test results.
 terminal_ Implements terminal reporting of the full testing process.
 
 
-internal plugins / core functionality
-=====================================
+plugins for generic reporting and failure logging
+=================================================
+
+pastebin_ submit failure or test session information to a pastebin service.
+
+resultlog_ resultlog plugin for machine-readable logging of test results.
+
+terminal_ Implements terminal reporting of the full testing process.
+
+
+misc plugins / core functionality
+=================================
+
+helpconfig_ provide version info, conftest/environment config names.
 
 pdb_ interactive debugging with the Python Debugger.
 

doc/test/plugin/links.txt

@@ -1,3 +1,4 @@
+.. _`helpconfig`: helpconfig.html
 .. _`terminal`: terminal.html
 .. _`pytest_recwarn.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.0.1/py/test/plugin/pytest_recwarn.py
 .. _`unittest`: unittest.html
@@ -15,6 +16,7 @@
 .. _`pytest_figleaf.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.0.1/py/test/plugin/pytest_figleaf.py
 .. _`pytest_hooklog.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.0.1/py/test/plugin/pytest_hooklog.py
 .. _`checkout the py.test development version`: ../../download.html#checkout
+.. _`pytest_helpconfig.py`: http://bitbucket.org/hpk42/py-trunk/raw/1.0.1/py/test/plugin/pytest_helpconfig.py
 .. _`oejskit`: oejskit.html
 .. _`doctest`: doctest.html
 .. _`get in contact`: ../../contact.html