add API documentation

docs/source/index.rst

@@ -18,6 +18,7 @@ Contents:
 
    patterns_loading
    patterns_enabling
+   managers
    history
 
 .. _setuptools entry points: http://packages.python.org/distribute/pkg_resources.html#convenience-api

docs/source/managers.rst

@@ -0,0 +1,40 @@
+===========================
+ Extension Manager Classes
+===========================
+
+DriverManager
+=============
+
+.. autoclass:: stevedore.driver.DriverManager
+   :members:
+
+HookManager
+===========
+
+.. autoclass:: stevedore.hook.HookManager
+   :members:
+
+NamedExtensionManager
+=====================
+
+.. autoclass:: stevedore.named.NamedExtensionManager
+   :members:
+
+EnabledExtensionManager
+=======================
+
+.. autoclass:: stevedore.enabled.EnabledExtensionManager
+   :members:
+
+ExtensionManager
+================
+
+.. autoclass:: stevedore.extension.ExtensionManager
+   :members:
+
+Extension
+=========
+
+.. autoclass:: stevedore.extension.Extension
+   :members:
+

run_sphinx

@@ -4,7 +4,7 @@
 set -x
 
 watchmedo shell-command \
-    --patterns='*.rst' \
-    --ignore-pattern='docs/build/*' \
+    --patterns='*.rst;*.py' \
+    --ignore-pattern='docs/build/*;*flymake*' \
     --recursive \
     --command='python setup.py build_sphinx'

stevedore/driver.py

@@ -3,6 +3,22 @@ from .hook import HookManager
 
 class DriverManager(HookManager):
     """Load a single plugin with a given name from the namespace.
+
+    :param namespace: The namespace for the entry points.
+    :type namespace: str
+    :param name: The name of the driver to load.
+    :type name: str
+    :param invoke_on_load: Boolean controlling whether to invoke the
+        object returned by the entry point after the driver is loaded.
+    :type invoke_on_load: bool
+    :param invoke_args: Positional arguments to pass when invoking
+        the object returned by the entry point. Only used if invoke_on_load
+        is True.
+    :type invoke_args: tuple
+    :param invoke_kwds: Named arguments to pass when invoking
+        the object returned by the entry point. Only used if invoke_on_load
+        is True.
+    :type invoke_kwds: dict
     """
 
     def __init__(self, namespace, name,

stevedore/enabled.py

@@ -3,6 +3,26 @@ from .extension import ExtensionManager
 
 class EnabledExtensionManager(ExtensionManager):
     """An ExtensionManager that only loads plugins that pass a check function.
+
+    The check_func should return a boolean, with ``True`` indicating
+    that the extension should be loaded and made available and
+    ``False`` indicating that the extension should be ignored.
+
+    :param namespace: The namespace for the entry points.
+    :type namespace: str
+    :param check_func: Function to determine which extensions to load.
+    :type check_func: callable
+    :param invoke_on_load: Boolean controlling whether to invoke the
+        object returned by the entry point after the driver is loaded.
+    :type invoke_on_load: bool
+    :param invoke_args: Positional arguments to pass when invoking
+        the object returned by the entry point. Only used if invoke_on_load
+        is True.
+    :type invoke_args: tuple
+    :param invoke_kwds: Named arguments to pass when invoking
+        the object returned by the entry point. Only used if invoke_on_load
+        is True.
+    :type invoke_kwds: dict
     """
 
     def __init__(self, namespace, check_func, invoke_on_load=False,

stevedore/extension.py

@@ -10,6 +10,16 @@ LOG = logging.getLogger(__name__)
 
 
 class Extension(object):
+    """Book-keeping object for tracking extensions.
+
+    :param name: The entry point name.
+    :type name: str
+    :param entry_point: The EntryPoint instance returned by :mod:`pkg_resources`.
+    :type entry_point: EntryPoint
+    :param plugin: The value returned by entry_point.load()
+    :param obj: The object returned by plugin(*args, **kwds) if the
+                manager invoked the extension on load.
+    """
 
     def __init__(self, name, entry_point, plugin, obj):
         self.name = name
@@ -19,6 +29,22 @@ class Extension(object):
 
 
 class ExtensionManager(object):
+    """Base class for all of the other managers.
+
+    :param namespace: The namespace for the entry points.
+    :type namespace: str
+    :param invoke_on_load: Boolean controlling whether to invoke the
+        object returned by the entry point after the driver is loaded.
+    :type invoke_on_load: bool
+    :param invoke_args: Positional arguments to pass when invoking
+        the object returned by the entry point. Only used if invoke_on_load
+        is True.
+    :type invoke_args: tuple
+    :param invoke_kwds: Named arguments to pass when invoking
+        the object returned by the entry point. Only used if invoke_on_load
+        is True.
+    :type invoke_kwds: dict
+    """
 
     def __init__(self, namespace, invoke_on_load=False, invoke_args=(), invoke_kwds={}):
         self.namespace = namespace
@@ -59,7 +85,7 @@ class ExtensionManager(object):
             def func(ext, *args, **kwds):
                 pass
 
-        The first argument to func(), 'ext', is the Extension
+        The first argument to func(), 'ext', is the :class:`Extension`
         instance.
 
         Exceptions raised from within func() are logged and ignored.

stevedore/hook.py

@@ -2,7 +2,23 @@ from .named import NamedExtensionManager
 
 
 class HookManager(NamedExtensionManager):
-    """Coordinate execution of extensions using a shared name.
+    """Coordinate execution of multiple extensions using a common name.
+
+    :param namespace: The namespace for the entry points.
+    :type namespace: str
+    :param name: The name of the hooks to load.
+    :type name: str
+    :param invoke_on_load: Boolean controlling whether to invoke the
+        object returned by the entry point after the driver is loaded.
+    :type invoke_on_load: bool
+    :param invoke_args: Positional arguments to pass when invoking
+        the object returned by the entry point. Only used if invoke_on_load
+        is True.
+    :type invoke_args: tuple
+    :param invoke_kwds: Named arguments to pass when invoking
+        the object returned by the entry point. Only used if invoke_on_load
+        is True.
+    :type invoke_kwds: dict
     """
 
     def __init__(self, namespace, name,

stevedore/named.py

@@ -6,6 +6,22 @@ class NamedExtensionManager(EnabledExtensionManager):
 
     This is useful for explictly enabling extensions in a
     configuration file, for example.
+
+    :param namespace: The namespace for the entry points.
+    :type namespace: str
+    :param name: The names of the extensions to load.
+    :type name: str
+    :param invoke_on_load: Boolean controlling whether to invoke the
+        object returned by the entry point after the driver is loaded.
+    :type invoke_on_load: bool
+    :param invoke_args: Positional arguments to pass when invoking
+        the object returned by the entry point. Only used if invoke_on_load
+        is True.
+    :type invoke_args: tuple
+    :param invoke_kwds: Named arguments to pass when invoking
+        the object returned by the entry point. Only used if invoke_on_load
+        is True.
+    :type invoke_kwds: dict
     """
 
     def __init__(self, namespace, names,