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

8 files changed, 39 insertions, 1 deletions

diff --git a/doc/source/conf.py b/doc/source/conf.py
index b55a285..825fc27 100644
--- a/doc/source/conf.py
+++ b/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.
diff --git a/doc/source/drivers.rst b/doc/source/drivers.rst
new file mode 100644
index 0000000..21b021a
--- /dev/null
+++ b/doc/source/drivers.rst
@@ -0,0 +1,6 @@
+===================
+ Available Drivers
+===================
+
+.. list-plugins:: oslo.messaging.drivers
+   :detailed:
diff --git a/doc/source/index.rst b/doc/source/index.rst
index c9c45b9..775f5a8 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -21,6 +21,7 @@ Contents
    exceptions
    opts
    conffixture
+   drivers
    AMQP1.0
    zmq_driver
    FAQ
diff --git a/oslo_messaging/_drivers/impl_fake.py b/oslo_messaging/_drivers/impl_fake.py
index bb32d12..36365e9 100644
--- a/oslo_messaging/_drivers/impl_fake.py
+++ b/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):
diff --git a/oslo_messaging/_drivers/impl_qpid.py b/oslo_messaging/_drivers/impl_qpid.py
index c4dd117..1333644 100644
--- a/oslo_messaging/_drivers/impl_qpid.py
+++ b/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):
diff --git a/oslo_messaging/_drivers/impl_rabbit.py b/oslo_messaging/_drivers/impl_rabbit.py
index 73902bf..83f3360 100644
--- a/oslo_messaging/_drivers/impl_rabbit.py
+++ b/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,
diff --git a/oslo_messaging/_drivers/impl_zmq.py b/oslo_messaging/_drivers/impl_zmq.py
index c3630db..f673b9c 100644
--- a/oslo_messaging/_drivers/impl_zmq.py
+++ b/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
 
diff --git a/oslo_messaging/_drivers/protocols/amqp/driver.py b/oslo_messaging/_drivers/protocols/amqp/driver.py
index cc2e1be..7d37b22 100644
--- a/oslo_messaging/_drivers/protocols/amqp/driver.py
+++ b/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=[]):