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)