1 files changed, 69 insertions, 0 deletions
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:
+