* add a script for generating plugin docs

* improve generation of docs
* refine plugins docs

--HG--
branch : 1.0.x

py/test/plugin/hookspec.py

@@ -1,10 +1,11 @@
 """
-py.test hooks / extension points 
+py.test plugin hooks 
 """
 
-# ------------------------------------------------------------------------------
-# Command line and configuration hooks 
-# ------------------------------------------------------------------------------
+# -------------------------------------------------------------------------
+# Command line and configuration 
+# -------------------------------------------------------------------------
+
 def pytest_addoption(parser):
     """ called before commandline parsing.  """
 
@@ -17,26 +18,12 @@ def pytest_configure(config):
 def pytest_namespace(config):
     """ return dict of name->object to become available at py.test.*"""
 
-
 def pytest_unconfigure(config):
     """ called before test process is exited.  """
 
-# ------------------------------------------------------------------------------
-# test Session related hooks 
-# ------------------------------------------------------------------------------
-
-def pytest_sessionstart(session):
-    """ before session.main() is called. """
-
-def pytest_sessionfinish(session, exitstatus, excrepr=None):
-    """ whole test run finishes. """
-
-def pytest_deselected(items):
-    """ repeatedly called for test items deselected by keyword. """
-
-# ------------------------------------------------------------------------------
+# -------------------------------------------------------------------------
 # collection hooks
-# ------------------------------------------------------------------------------
+# -------------------------------------------------------------------------
 
 def pytest_collect_directory(path, parent):
     """ return Collection node or None for the given path. """
@@ -50,6 +37,9 @@ def pytest_collectstart(collector):
 def pytest_collectreport(rep):
     """ collector finished collecting. """
 
+def pytest_deselected(items):
+    """ called for test items deselected by keyword. """
+
 def pytest_make_collect_report(collector):
     """ perform a collection and return a collection. """ 
 pytest_make_collect_report.firstresult = True
@@ -58,9 +48,9 @@ pytest_make_collect_report.firstresult = True
 def pytest_itemstart(item, node=None):
     """ test item gets collected. """
 
-# ------------------------------------------------------------------------------
-# Python test function related hooks 
-# ------------------------------------------------------------------------------
+# -------------------------------------------------------------------------
+# Python test function related hooks
+# -------------------------------------------------------------------------
 
 def pytest_pycollect_makeitem(collector, name, obj):
     """ return custom item/collector for a python object in a module, or None.  """
@@ -73,9 +63,14 @@ pytest_pyfunc_call.firstresult = True
 def pytest_generate_tests(metafunc):
     """ generate (multiple) parametrized calls to a test function."""
 
-# ------------------------------------------------------------------------------
+# -------------------------------------------------------------------------
 # generic runtest related hooks 
-# ------------------------------------------------------------------------------
+# -------------------------------------------------------------------------
+
+def pytest_runtest_protocol(item):
+    """ implement fixture, run and report protocol. """
+pytest_runtest_protocol.firstresult = True
+
 def pytest_runtest_setup(item):
     """ called before pytest_runtest_call(). """ 
 
@@ -85,10 +80,6 @@ def pytest_runtest_call(item):
 def pytest_runtest_teardown(item):
     """ called after pytest_runtest_call(). """ 
 
-def pytest_runtest_protocol(item):
-    """ run given test item and return test report. """ 
-pytest_runtest_protocol.firstresult = True
-
 def pytest_runtest_makereport(item, call):
     """ make ItemTestReport for the given item and call outcome. """ 
 pytest_runtest_makereport.firstresult = True
@@ -96,9 +87,20 @@ pytest_runtest_makereport.firstresult = True
 def pytest_runtest_logreport(rep):
     """ process item test report. """ 
 
-# ------------------------------------------------------------------------------
-# generic reporting hooks (invoked from pytest_terminal.py) 
-# ------------------------------------------------------------------------------
+# -------------------------------------------------------------------------
+# test session related hooks 
+# -------------------------------------------------------------------------
+
+def pytest_sessionstart(session):
+    """ before session.main() is called. """
+
+def pytest_sessionfinish(session, exitstatus, excrepr=None):
+    """ whole test run finishes. """
+
+# -------------------------------------------------------------------------
+# generic reporting hooks (invoked from pytest_terminal)
+# -------------------------------------------------------------------------
+
 def pytest_report_teststatus(rep):
     """ return shortletter and verbose word. """
 pytest_report_teststatus.firstresult = True
@@ -112,33 +114,17 @@ def pytest_report_iteminfo(item):
     """
 pytest_report_iteminfo.firstresult = True
 
-# ------------------------------------------------------------------------------
+# -------------------------------------------------------------------------
 # doctest hooks 
-# ------------------------------------------------------------------------------
+# -------------------------------------------------------------------------
+
 def pytest_doctest_prepare_content(content):
     """ return processed content for a given doctest"""
 pytest_doctest_prepare_content.firstresult = True
 
-
-# ------------------------------------------------------------------------------
-# misc hooks 
-# ------------------------------------------------------------------------------
-
-def pytest_plugin_registered(plugin):
-    """ a new py lib plugin got registered. """
-
-def pytest_plugin_unregistered(plugin):
-    """ a py lib plugin got unregistered. """
-
-def pytest_internalerror(excrepr):
-    """ called for internal errors. """
-
-def pytest_trace(category, msg):
-    """ called for debug info. """ 
-
-# ------------------------------------------------------------------------------
+# -------------------------------------------------------------------------
 # distributed testing 
-# ------------------------------------------------------------------------------
+# -------------------------------------------------------------------------
 
 def pytest_testnodeready(node):
     """ Test Node is ready to operate. """
@@ -152,3 +138,19 @@ def pytest_rescheduleitems(items):
 def pytest_looponfailinfo(failreports, rootdirs):
     """ info for repeating failing tests. """
 
+
+# -------------------------------------------------------------------------
+# internal debugging hooks 
+# -------------------------------------------------------------------------
+
+def pytest_plugin_registered(plugin):
+    """ a new py lib plugin got registered. """
+
+def pytest_plugin_unregistered(plugin):
+    """ a py lib plugin got unregistered. """
+
+def pytest_internalerror(excrepr):
+    """ called for internal errors. """
+
+def pytest_trace(category, msg):
+    """ called for debug info. """