README improvements

README.rst

@@ -1,19 +1,72 @@
+pluggy - A minimalist production ready plugin system
+====================================================
+|pypi| |versions| |travis| |appveyor|
 
-Plugin registration and hook calling for Python
-===============================================
 
-.. image:: https://img.shields.io/pypi/v/pluggy.svg
+This is the core framework used by the `pytest`_, `tox`_, and `devpi`_ projects.
+
+Please `read the docs`_ to learn more!
+
+A definitive example
+********************
+.. code-block:: python
+
+    import pluggy
+
+    hookspec = pluggy.HookspecMarker("myproject")
+    hookimpl = pluggy.HookimplMarker("myproject")
+
+
+    class MySpec(object):
+        """A hook specification namespace.
+        """
+        @hookspec
+        def myhook(self, arg1, arg2):
+            """My special little hook that you can customize.
+            """
+
+
+    class Plugin_1(object):
+        """A hook implementation namespace.
+        """
+        @hookimpl
+        def myhook(self, arg1, arg2):
+            print("inside Plugin_1.myhook()")
+            return arg1 + arg2
+
+
+    class Plugin_2(object):
+        """A 2nd hook implementation namespace.
+        """
+        @hookimpl
+        def myhook(self, arg1, arg2):
+            print("inside Plugin_2.myhook()")
+            return arg1 - arg2
+
+
+    # create a manager and add the spec
+    pm = pluggy.PluginManager("myproject")
+    pm.add_hookspecs(MySpec)
+
+    # register plugins
+    pm.register(Plugin_1())
+    pm.register(Plugin_2())
+
+    # call our `myhook` hook
+    results = pm.hook.myhook(arg1=1, arg2=2)
+    print(results)
+
+
+.. badges
+.. |pypi| image:: https://img.shields.io/pypi/v/pluggy.svg
     :target: https://pypi.python.org/pypi/pluggy
-.. image:: https://img.shields.io/pypi/pyversions/pluggy.svg
+.. |versions| image:: https://img.shields.io/pypi/pyversions/pluggy.svg
     :target: https://pypi.python.org/pypi/pluggy
-.. image:: https://img.shields.io/travis/pytest-dev/pluggy/master.svg
+.. |travis| image:: https://img.shields.io/travis/pytest-dev/pluggy/master.svg
     :target: https://travis-ci.org/pytest-dev/pluggy
-.. image:: https://img.shields.io/appveyor/ci/pytestbot/pluggy/master.svg
+.. |appveyor| image:: https://img.shields.io/appveyor/ci/pytestbot/pluggy/master.svg
     :target: https://ci.appveyor.com/project/pytestbot/pluggy
 
-This is the core plugin system used by the `pytest`_, `tox`_, and `devpi`_ projects.
-Please `read the docs`_ to learn more!
-
 .. links
 .. _pytest:
     http://pytest.org

tox.ini

@@ -18,18 +18,17 @@ deps=
 deps =
   flake8
   restructuredtext_lint
+  pygments
 commands =
   flake8 pluggy.py setup.py testing
   rst-lint CHANGELOG.rst README.rst
 
 [testenv:docs]
 deps =
-    sphinx
-    pygments
+  sphinx
+  pygments
 commands =
-    sphinx-build \
-        -b html \
-        {toxinidir}/docs {toxinidir}/build/html-docs
+  sphinx-build -b html {toxinidir}/docs {toxinidir}/build/html-docs
 
 [pytest]
 minversion=2.0