From 0a8c5145d4d9e82aa18729ff03a38fc725a02d1b Mon Sep 17 00:00:00 2001
From: Doug Hellmann <doug@doughellmann.com>
Date: Sat, 16 May 2015 15:13:31 -0400
Subject: [PATCH] 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                               | 6 +++++-
 doc/source/drivers.rst                           | 6 ++++++
 doc/source/index.rst                             | 1 +
 oslo_messaging/_drivers/impl_fake.py             | 6 ++++++
 oslo_messaging/_drivers/impl_qpid.py             | 3 +++
 oslo_messaging/_drivers/impl_rabbit.py           | 9 +++++++++
 oslo_messaging/_drivers/impl_zmq.py              | 5 +++++
 oslo_messaging/_drivers/protocols/amqp/driver.py | 4 ++++
 8 files changed, 39 insertions(+), 1 deletion(-)
 create mode 100644 doc/source/drivers.rst

diff --git a/doc/source/conf.py b/doc/source/conf.py
index b55a2854b..825fc278e 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 000000000..21b021aea
--- /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 c9c45b9c0..775f5a818 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 bb32d12d5..36365e91c 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 c4dd11784..1333644d9 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 73902bf61..83f3360fc 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 c3630db6b..f673b9c06 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 cc2e1be8e..7d37b22fa 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=[]):