Spring cleaning

doc/plugins.rst

@@ -5,74 +5,90 @@ tox plugins
 
 .. versionadded:: 2.0
 
-With tox-2.0 a few aspects of tox running can be experimentally modified
-by writing hook functions.  The list of of available hook function is
-to grow over time on a per-need basis.
+A growing number of `pluggy`_ hooks make tox extendable by writing plugins.
 
 
-writing a setuptools entrypoints plugin
+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:
+You can create a new tox plugin with all bells and whistles via a `Cookiecutter`_ template (see `cookiecutter-tox-plugin <https://github.com/tox-dev/cookiecutter-tox-plugin>`_) - this will create a complete pypi-releasable, documented project with license, documentation and CI.
 
-.. code-block:: python
-
-    # content of setup.py
-    from setuptools import setup
+.. code-block:: console
 
-    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'],
-        )
+    $ pip install -U cookiecutter
+    $ cookiecutter gh:tox-dev/cookiecutter-tox-plugin
 
-If installed, the ``entry_points`` part will make tox see and integrate
-your plugin during startup.
 
-You can install the plugin for development ("in-place") via:
+Tutorial: a minimal tox plugin
+------------------------------
 
-.. code-block:: shell
+To create a working plugin you need at least a python project with a tox entry point and a python
+module implementing one or more of the pluggy based hooks tox specifies (using the
+``@tox.hookimpl`` decorator as marker).
 
-    pip install -e .
+Let us consider you want to extent tox behaviour by displaying fireworks at the end of a
+successful tox run (we won't go into the details of how to display fireworks though).
 
-and later publish it via something like:
+minimal structure:
 
-.. code-block:: shell
+.. code-block:: console
 
-    python setup.py sdist register upload
+    $ mkdir tox-fireworks
+    $ cd tox-fireworks
+    $ touch tox_fireworks.py
+    $ touch setup.py
 
-
-Writing hook implementations
-----------------------------
-
-A plugin module defines one or more hook implementation functions
-by decorating them with tox's ``hookimpl`` marker:
+contents of ``tox_fireworks.py``:
 
 .. code-block:: python
 
-    from tox import hookimpl
+    import pluggy
+
+    hookimpl = pluggy.HookimplMarker("tox")
 
     @hookimpl
     def tox_addoption(parser):
-        # add your own command line options
-
+        """Add command line option to display fireworks on request."""
 
     @hookimpl
     def tox_configure(config):
-        # post process tox configuration after cmdline/ini file have
-        # been parsed
+        """Post process config after parsing."""
+
+    @hookimpl
+    def tox_runenvreport(config):
+        """Display fireworks if all was fine and requested."""
 
-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.
 
+contents of ``setup.py``:
 
+.. code-block:: python
+
+    from setuptools import setup
+
+    setup(name='tox-fireworks', py_modules=['tox_fireworks'],
+          entry_points={'tox': ['fireworks = tox_fireworks']})
+
+Using the  **tox-** prefix in ``tox-fireworks`` is necessary for it to be an official plugin and
+makes finding it easy with e.g. ``pip search 'tox-'`` once it is released on PyPi.
+
+To make your new plugin discoverable by tox, you need to install it. During development you should
+install it with ``-e`` or ``--editable``, so that changes to the code are immediately active:
+
+.. code-block:: console
+
+    pip install -e </path/to/tox-fireworks>
+
+If you think the rest of the world could profit using your plugin you can publish it to PyPi.
+Add some more meta data to ``setup.py`` (see the cookiecutter for a complete example) and publish
+it like:
+
+.. code-block:: console
+
+    $ cd </path/to/tox-fireworks>
+    $ python setup.py sdist bdist_wheel upload
+
+For more information about packaging Python projects see the
+`Python Packaging User Guide <https://packaging.python.org/>`_.
 
 tox hook specifications and related API
 ---------------------------------------
@@ -94,3 +110,7 @@ tox hook specifications and related API
 
 .. autoclass:: tox.session.Session()
     :members:
+
+
+.. _`Cookiecutter`: https://cookiecutter.readthedocs.io
+.. _`pluggy`: https://pluggy.readthedocs.io

setup.py

@@ -43,7 +43,7 @@ def main():
         author='holger krekel',
         author_email='holger@merlinux.eu',
         packages=['tox'],
-        entry_points={'console_scripts': ['tox=tox.session:run_main',
+        entry_points={'console_scripts': ['tox=tox:cmdline',
                                           'tox-quickstart=tox._quickstart:main']},
         python_requires='>=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3.*',
         setup_requires=['setuptools_scm'],