From 3c18c6f440d4e31190c51596b2063c1ca9efc7f9 Mon Sep 17 00:00:00 2001
From: Sean McGinnis <sean_mcginnis@dell.com>
Date: Sat, 23 Jul 2016 11:36:57 -0500
Subject: [PATCH] Add interface documentation to driver devref

Link the docstring generated documentation for the driver interfaces into
the drivers devref page for easy access to driver method documentation.

Change-Id: Ie22599fef99ebfac12f3b9bb251ae5bdfff4bff6
---
 doc/source/devref/drivers.rst | 60 +++++++++++++++++++++++++++++++++++
 tools/generate_driver_list.py |  3 +-
 2 files changed, 62 insertions(+), 1 deletion(-)

diff --git a/doc/source/devref/drivers.rst b/doc/source/devref/drivers.rst
index ddd9f08ce..f51215e86 100644
--- a/doc/source/devref/drivers.rst
+++ b/doc/source/devref/drivers.rst
@@ -82,3 +82,63 @@ tests.
 The details for the required volume driver interfaces can be found in the
 ``cinder/interface/volume_*_driver.py`` source.
 
+Driver Development Documentations
+---------------------------------
+
+The LVM driver is our reference for all new driver implementations. The
+information below can provide additional documentation for the methods that
+volume drivers need to implement.
+
+Base Driver Interface
+`````````````````````
+The methods documented below are the minimum required interface for a volume
+driver to support. All methods from this interface must be implemented
+in order to be an official Cinder volume driver.
+
+.. automodule:: cinder.interface.volume_driver
+  :members:
+
+
+Snapshot Interface
+``````````````````
+Another required interface for a volume driver to be fully compatible is the
+ability to create and manage snapshots. Due to legacy constraints, this
+interface is not included in the base driver interface above.
+
+Work is being done to address those legacy issues. Once that is complete, this
+interface will be merged with the base driver interface.
+
+.. automodule:: cinder.interface.volume_snapshot_driver
+  :members:
+
+
+Manage/Unmanage Support
+```````````````````````
+An optional feature a volume backend can support is the ability to manage
+existing volumes or unmanage volumes - keep the volume on the storage backend
+but no longer manage it through Cinder.
+
+To support this functionality, volume drivers must implement these methods:
+
+.. automodule:: cinder.interface.volume_management_driver
+  :members:
+
+
+Manage/Unmanage Snapshot Support
+````````````````````````````````
+In addition to the ability to manage and unmanage volumes, Cinder backend
+drivers may also support managing and unmanaging volume snapshots. These
+additional methods must be implemented to support these operations.
+
+.. automodule:: cinder.interface.volume_snapshotmanagement_driver
+  :members:
+
+Volume Consistency Groups
+`````````````````````````
+Some storage backends support the ability to group volumes and create write
+consistent snapshots across the group. In order to support these operations,
+the following interface must be implemented by the driver.
+
+.. automodule:: cinder.interface.volume_consistencygroup_driver
+  :members:
+
diff --git a/tools/generate_driver_list.py b/tools/generate_driver_list.py
index 61a5edd3e..ece213c9c 100755
--- a/tools/generate_driver_list.py
+++ b/tools/generate_driver_list.py
@@ -34,7 +34,8 @@ def print_drivers(drivers, config_name):
         if driver.version:
             print('* Version: %s' % driver.version)
         print('* %s=%s' % (config_name, driver.class_fqn))
-        print('* Description:')
+        print('* Description::')
+        print('')
         format_description(driver.desc)
         print('')
     print('')