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=[]):