Sphinx docs

README.rst

@@ -11,7 +11,15 @@ Plugin registration and hook calling for Python
 .. image:: https://img.shields.io/appveyor/ci/pytestbot/pluggy/master.svg
     :target: https://ci.appveyor.com/project/pytestbot/pluggy
 
-This is the plugin manager as used by [pytest](http://pytest.org), [tox](https://tox.readthedocs.org), [devpi](http://doc.devpi.net) and probably other projects.
+This is the core plugin system used by the `pytest`_, `tox`_, and `devpi`_ projects.
+Please `read the docs`_ to learn more!
 
-During the 0.x series this plugin does not have much documentation
-except extensive docstrings in the pluggy.py module.
+.. links
+.. _pytest:
+    http://pytest.org
+.. _tox:
+    https://tox.readthedocs.org
+.. _devpi:
+    http://doc.devpi.net
+.. _read the docs:
+   https://pluggy.readthedocs.io/en/latest/

docs/api_reference.rst

@@ -1,11 +1,7 @@
-
-
 Api Reference
 =============
 
 .. automodule:: pluggy
     :members:
     :undoc-members:
     :show-inheritance:
-
-

docs/conf.py

@@ -33,7 +33,19 @@
 language = None
 
 pygments_style = 'sphinx'
+html_logo = '_static/img/plug.png'
 html_theme = 'alabaster'
+html_theme_options = {
+    # 'logo': 'img/plug.png',
+    # 'logo_name': 'true',
+    'description': 'The `pytest` plugin system',
+    'github_user': 'pytest-dev',
+    'github_repo': 'pluggy',
+    'github_button': 'true',
+    'github_banner': 'true',
+    'page_width': '1080px',
+    'fixed_sidebar': 'false',
+}
 html_static_path = ['_static']
 
 # One entry per manual page. List of tuples

docs/examples/firstexample.py

@@ -0,0 +1,44 @@
+import pluggy
+
+hookspec = pluggy.HookspecMarker("myproject")
+hookimpl = pluggy.HookimplMarker("myproject")
+
+
+class MySpec:
+    """A hook specification namespace.
+    """
+    @hookspec
+    def myhook(self, arg1, arg2):
+        """My special little hook that you can customize.
+        """
+
+
+class Plugin_1:
+    """A hook implementation namespace.
+    """
+    @hookimpl
+    def myhook(self, arg1, arg2):
+        print("inside Plugin_1.myhook()")
+        return arg1 + arg2
+
+
+class Plugin_2:
+    """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)