Document the transport backend driver interface

Add detailed documentation to the driver API to help driver developers
create drivers that behave consistently.  Specifically prescribes a
set of operational characteristics that a driver must conform to in
order to provide consistent behavior across different implementations.

Change-Id: Icb251ee724f9a0ac4fede702a367910de4ba95e3

2 files changed, 76 insertions, 0 deletions

diff --git a/doc/source/driver-dev-guide.rst b/doc/source/driver-dev-guide.rst
new file mode 100644
index 0000000..0062575
--- /dev/null
+++ b/doc/source/driver-dev-guide.rst
@@ -0,0 +1,75 @@
+---------------------------------------
+Guide for Transport Driver Implementors
+---------------------------------------
+
+.. currentmodule:: oslo_messaging
+
+.. automodule:: oslo_messaging._drivers.base
+
+============
+Introduction
+============
+
+This document is a *best practices* guide for the developer interested
+in creating a new transport driver for Oslo.Messaging.  It should also
+be used by maintainers as a reference for proper driver behavior.
+This document will describe the driver interface and prescribe the
+expected behavior of any driver implemented to this interface.
+
+**Note well:** The API described in this document is internal to the
+oslo.messaging library and therefore **private**.  Under no
+circumstances should this API be referenced by code external to the
+oslo.messaging library.
+
+================
+Driver Interface
+================
+
+The driver interface is defined by a set of abstract base classes. The
+developer creates a driver by defining concrete classes from these
+bases.  The derived classes embody the logic that is specific for the
+messaging back-end that is to be supported.
+
+These base classes are defined in the *base.py* file in the *_drivers*
+subdirectory.
+
+===============
+IncomingMessage
+===============
+
+.. autoclass:: IncomingMessage
+   :members:
+
+==================
+RpcIncomingMessage
+==================
+
+.. autoclass:: RpcIncomingMessage
+   :members:
+
+========
+Listener
+========
+
+.. autoclass:: Listener
+   :members:
+
+=================
+PollStyleListener
+=================
+
+.. autoclass:: PollStyleListener
+   :members:
+
+==========
+BaseDriver
+==========
+
+.. autoclass:: BaseDriver
+   :members:
+
+
+
+
+
+
diff --git a/doc/source/index.rst b/doc/source/index.rst
index b497820..8125127 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -27,6 +27,7 @@ Contents
    AMQP1.0
    pika_driver
    zmq_driver
+   driver-dev-guide
    FAQ
    contributing