introduce little plugin system based on pluggy

and refactor/streamline some code with relation to
getting executables

3 files changed, 80 insertions, 7 deletions

diff --git a/doc/conf.py b/doc/conf.py
index 9c573d7..73f5168 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -48,8 +48,8 @@ copyright = u'2013, holger krekel and others'
 # built documents.
 #
 # The short X.Y version.
-release = "1.9"
-version = "1.9.0"
+release = "2.0"
+version = "2.0.0"
 # The full version, including alpha/beta/rc tags.
 
 # The language for content autogenerated by Sphinx. Refer to documentation
diff --git a/doc/index.txt b/doc/index.txt
index 17d063d..ed594cd 100644
--- a/doc/index.txt
+++ b/doc/index.txt
@@ -5,7 +5,7 @@ vision: standardize testing in Python
 ---------------------------------------------
 
 ``tox`` aims to automate and standardize testing in Python.  It is part
-of a larger vision of easing the packaging, testing and release process 
+of a larger vision of easing the packaging, testing and release process
 of Python software.
 
 What is Tox?
@@ -21,6 +21,7 @@ Tox is a generic virtualenv_ management and test command line tool you can use f
 * acting as a frontend to Continuous Integration servers, greatly
   reducing boilerplate and merging CI and shell-based testing.
 
+
 Basic example
 -----------------
 
@@ -62,10 +63,10 @@ Current features
 
     - test-tool agnostic: runs py.test, nose or unittests in a uniform manner
 
-* supports :ref:`using different / multiple PyPI index servers  <multiindex>`
+* :doc:`(new in 2.0) plugin system <plugins>` to modify tox execution with simple hooks.
 
 * uses pip_ and setuptools_ by default.  Experimental
-  support for configuring the installer command 
+  support for configuring the installer command
   through :confval:`install_command=ARGV`.
 
 * **cross-Python compatible**: CPython-2.6, 2.7, 3.2 and higher,
@@ -74,11 +75,11 @@ Current features
 * **cross-platform**: Windows and Unix style environments
 
 * **integrates with continuous integration servers** like Jenkins_
-  (formerly known as Hudson) and helps you to avoid boilerplatish 
+  (formerly known as Hudson) and helps you to avoid boilerplatish
   and platform-specific build-step hacks.
 
 * **full interoperability with devpi**: is integrated with and
-  is used for testing in the devpi_ system, a versatile pypi 
+  is used for testing in the devpi_ system, a versatile pypi
   index server and release managing tool.
 
 * **driven by a simple ini-style config file**
@@ -89,6 +90,9 @@ Current features
 
 * **professionally** :doc:`supported <support>`
 
+* supports :ref:`using different / multiple PyPI index servers  <multiindex>`
+
+
 .. _pypy: http://pypy.org
 
 .. _`tox.ini`: :doc:configfile
diff --git a/doc/plugins.txt b/doc/plugins.txt
new file mode 100644
index 0000000..61e4408
--- /dev/null
+++ b/doc/plugins.txt
@@ -0,0 +1,69 @@
+.. be in -*- rst -*- mode!
+
+tox plugins
+===========
+
+.. versionadded:: 2.0
+
+With tox-2.0 a few aspects of tox running can be experimentally modified
+by writing hook functions.  We expect the list of hook function to grow
+over time.
+
+writing a setuptools entrypoints plugin
+---------------------------------------
+
+If you have a ``tox_MYPLUGIN.py`` module you could use the following
+rough ``setup.py`` to make it into a package which you can upload to the
+Python packaging index::
+
+    # content of setup.py
+    from setuptools import setup
+
+    if __name__ == "__main__":
+        setup(
+            name='tox-MYPLUGIN',
+            description='tox plugin decsription',
+            license="MIT license",
+            version='0.1',
+            py_modules=['tox_MYPLUGIN'],
+            entry_points={'tox': ['MYPLUGIN = tox_MYPLUGIN']},
+            install_requires=['tox>=2.0'],
+        )
+
+You can then install the plugin to develop it via::
+
+    pip install -e .
+
+and later publish it.
+
+The ``entry_points`` part allows tox to see your plugin during startup.
+
+
+Writing hook implementations
+----------------------------
+
+A plugin module needs can define one or more hook implementation functions::
+
+    from tox import hookimpl
+
+    @hookimpl
+    def tox_addoption(parser):
+        # add your own command line options
+
+
+    @hookimpl
+    def tox_configure(config):
+        # post process tox configuration after cmdline/ini file have
+        # been parsed
+
+If you put this into a module and make it pypi-installable with the ``tox``
+entry point you'll get your code executed as part of a tox run.
+
+
+
+tox hook specifications
+----------------------------
+
+.. automodule:: tox.hookspecs
+    :members:
+