Add drivers to the documentation

Use stevedore.sphinxext to populate a new page listing all available
drivers.

Add docstrings to the driver classes, including references to more
extensive documentation if it is available.

Depends-on: I1a24f9326b4e54174d9dc0ae366315fe29c3ac1b
Depends-on: Ie715f98fe0d3cba8b2f4f6235e7c2b6f79be7ea0

Change-Id: Ief0aa05e6deba0126d63faf13497d0fe0539e08d

doc/source/conf.py

@@ -8,7 +8,11 @@ sys.path.insert(0, os.path.abspath('../..'))
 
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc', 'oslosphinx']
+extensions = [
+    'sphinx.ext.autodoc',
+    'oslosphinx',
+    'stevedore.sphinxext',
+]
 
 # autodoc generation is a bit aggressive and a nuisance when doing heavy
 # text edit cycles.

doc/source/drivers.rst

@@ -0,0 +1,6 @@
+===================
+ Available Drivers
+===================
+
+.. list-plugins:: oslo.messaging.drivers
+   :detailed:

doc/source/index.rst

@@ -21,6 +21,7 @@ Contents
    exceptions
    opts
    conffixture
+   drivers
    AMQP1.0
    zmq_driver
    FAQ

oslo_messaging/_drivers/impl_fake.py

@@ -154,6 +154,12 @@ class FakeExchangeManager(object):
 
 
 class FakeDriver(base.BaseDriver):
+    """Fake driver used for testing.
+
+    This driver passes messages in memory, and should only be used for
+    unit tests.
+
+    """
 
     def __init__(self, conf, url, default_exchange=None,
                  allowed_remote_exmods=None):

oslo_messaging/_drivers/impl_qpid.py

@@ -764,6 +764,9 @@ class Connection(object):
 
 
 class QpidDriver(amqpdriver.AMQPDriverBase):
+    """qpidd Driver
+
+    """
 
     def __init__(self, conf, url,
                  default_exchange=None, allowed_remote_exmods=None):

oslo_messaging/_drivers/impl_rabbit.py

@@ -1086,6 +1086,15 @@ class Connection(object):
 
 
 class RabbitDriver(amqpdriver.AMQPDriverBase):
+    """RabbitMQ Driver
+
+    The ``rabbit`` driver is the default driver used in OpenStack's
+    integration tests.
+
+    The driver is aliased as ``kombu`` to support upgrading existing
+    installations with older settings.
+
+    """
 
     def __init__(self, conf, url,
                  default_exchange=None,

oslo_messaging/_drivers/impl_zmq.py

@@ -988,6 +988,11 @@ class ZmqClientPoolManager(object):
 
 
 class ZmqDriver(base.BaseDriver):
+    """ZeroMQ Driver
+
+    See :doc:`zmq_driver` for details.
+
+    """
 
     # FIXME(markmc): allow this driver to be used without eventlet
 

oslo_messaging/_drivers/protocols/amqp/driver.py

@@ -121,6 +121,10 @@ class ProtonListener(base.Listener):
 
 
 class ProtonDriver(base.BaseDriver):
+    """AMQP 1.0 Driver
+
+    See :doc:`AMQP1.0` for details.
+    """
 
     def __init__(self, conf, url,
                  default_exchange=None, allowed_remote_exmods=[]):