start documenting hooks, improve hookspec docstrings a bit

--HG--
branch : trunk

doc/customize.txt

@@ -228,83 +228,39 @@ the ``--traceconfig`` option.
 .. _`well specified hooks`:
 .. _`implement hooks`:
 
-Important py.test hooks
+py.test hook reference
 ====================================
 
-py.test calls hooks functions to implement its `test collection`_,
-running and reporting process.  When py.test loads a plugin it validates
-that all hook functions conform to the `hook definition specification`_.
+hook specification and validation
+-----------------------------------------
 
-The hook function name and its
-argument names need to match exactly but it is allowed for an implementation
-to accept *less* parameters.  You'll get useful errors on mistyped hook or
-argument names.  Read on for some introductory information on particular
-hooks.  It's sensible to look at existing plugins so see example usages
-and start off with your own plugin.
+py.test calls hook functions to implement initialization, running,
+test execution and reporting.  When py.test loads a plugin it validates
+that all hook functions conform to their respective hook specification.
+Each hook function name and its argument names need to match a hook
+specification exactly but it is allowed for a hook function to accept 
+*less* parameters than specified.  If you mistype argument names or the
+hook name itself you get useful errors.
 
-.. _`hook definition specification`: plugin/hookspec.html
-
-.. _`configuration hooks`:
-
-command line parsing and configuration hooks
+initialisation, command line and configuration hooks
 --------------------------------------------------------------------
 
-When the `test tool starts up`_ it will invoke all hooks that add
-command line options in the python standard optparse style.
-
-.. sourcecode:: python
-
-    def pytest_addoption(parser):
-        """ add command line options. """"
-        parser.addoption("--myopt", dest="myopt", action="store_true")
-
-After all these hooks have been called, the command line is parser
-and a ``config`` object is created and another hook is invoked,
-for example:
-
-.. sourcecode:: python
-
-    def pytest_configure(config):
-        config.getvalue("myopt")
-
-When the test run finishes this corresponding finalizer hook is called:
-
-.. sourcecode:: python
-
-    def pytest_unconfigure(config):
-        ...
-
-
-adding global py.test helpers and functionality
---------------------------------------------------------------------
-
-If you want to make global helper functions or objects available
-to your test code you can implement:
-
-.. sourcecode:: python
-
-    def pytest_namespace():
-        """ return dictionary with items to be made available on py.test. namespace """
-
-All such returned items will be made available directly on
-the ``py.test`` namespace.
-
-If you want to provide helpers that are specific to a test function run or need
-to be setup per test function run, please refer to the `funcargs mechanism`_.
-
-.. _`funcargs mechanism`: funcargs.html
+.. currentmodule:: pytest.hookspec
 
+.. autofunction:: pytest_namespace
+.. autofunction:: pytest_addoption
+.. autofunction:: pytest_cmdline_main
+.. autofunction:: pytest_configure
+.. autofunction:: pytest_unconfigure
 
 generic "runtest" hooks
 ------------------------------
 
 Each test item is usually executed by calling the following three hooks:
 
-.. sourcecode:: python
-
-    pytest_runtest_setup(item)
-    pytest_runtest_call(item)
-    pytest_runtest_teardown(item)
+.. autofunction:: pytest_runtest_setup
+.. autofunction:: pytest_runtest_call
+.. autofunction:: pytest_runtest_teardown
 
 For each of the three invocations a `call object`_ encapsulates
 information about the outcome of the call and is subsequently used

doc/links.inc

@@ -11,4 +11,4 @@
 .. _mercurial: http://mercurial.selenic.com/wiki/
 .. _`setuptools`: http://pypi.python.org/pypi/setuptools
 .. _`distribute`: http://pypi.python.org/pypi/distribute
-.. _hudon: http://hudson-ci.org/
+.. _hudson: http://hudson-ci.org/

doc/reporting.txt

@@ -1,8 +1,6 @@
-Sending output to files or to remote services
+Sending test report output to XML files or to remote services
 =================================================================
 
-
-
 creating JUnitXML format files
 ----------------------------------------------------
 

doc/skipping.txt

@@ -80,7 +80,7 @@ apply the function will be skipped.
 
 .. _xfail:
 
-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

doc/test/plugin/xmlresult.txt

@@ -1,9 +0,0 @@
-pytest_xmlresult plugin (EXTERNAL)
-==========================================
-
-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/

pytest/hookspec.py

@@ -3,34 +3,41 @@ hook specifications for py.test plugins
 """
 
 # -------------------------------------------------------------------------
-# Command line and configuration
+# Initialization
 # -------------------------------------------------------------------------
 
 def pytest_namespace():
-    "return dict of name->object which will get stored at py.test. namespace"
+    """return dict of name->object to be made globally available in
+    the py.test/pytest namespace.  This hook is called before command
+    line options are fully parsed.  If you want to provide helper functions
+    that can interact with a test function invocation, please refer to 
+    :ref:`funcarg mechanism`.
+    """
 
 def pytest_addoption(parser):
-    "add optparse-style options via parser.addoption."
+    """allows to add optparse-style command line options via a call to 
+    ``parser.addoption(...)``."""
 
 def pytest_addhooks(pluginmanager):
-    "add hooks via pluginmanager.registerhooks(module)"
+    "allows to add new hooks via pluginmanager.registerhooks(module)"
+
+def pytest_cmdline_main(config):
+    """ called for performing the main command line action. The default
+    implementation will invoke the configure hooks and runtest_mainloop. """
+pytest_cmdline_main.firstresult = True
 
 def pytest_configure(config):
     """ called after command line options have been parsed.
         and all plugins and initial conftest files been loaded.
     """
 
-def pytest_cmdline_main(config):
-    """ called for performing the main (cmdline) action. """
-pytest_cmdline_main.firstresult = True
+def pytest_unconfigure(config):
+    """ called before test process is exited.  """
 
 def pytest_runtest_mainloop(session):
     """ called for performing the main runtest loop (after collection. """
 pytest_runtest_mainloop.firstresult = True
 
-def pytest_unconfigure(config):
-    """ called before test process is exited.  """
-
 # -------------------------------------------------------------------------
 # collection hooks
 # -------------------------------------------------------------------------

pytest/pluginmanager.py

@@ -15,7 +15,7 @@ def check_old_use(mod, modname):
 
 class PluginManager(object):
     def __init__(self):
-        from pytest.plugin import hookspec
+        from pytest import hookspec
         self.registry = Registry()
         self._name2plugin = {}
         self._hints = []