Merge "Add driver list to doc build"

.gitignore

@@ -30,6 +30,7 @@ tags
 # Files created by Sphinx build
 doc/build
 doc/source/_static/cinder.conf.sample
+doc/source/drivers.rst
 
 #Files created for API reference
 api-ref/build

doc/ext/cinder_driverlist.py

@@ -0,0 +1,24 @@
+# Copyright 2016 Dell Inc.
+# All Rights Reserved.
+#
+#    Licensed under the Apache License, Version 2.0 (the "License"); you may
+#    not use this file except in compliance with the License. You may obtain
+#    a copy of the License at
+#
+#         http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+#    WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+#    License for the specific language governing permissions and limitations
+#    under the License.
+#
+
+from cinder import utils
+
+
+def setup(app):
+    print('** Generating driver list...')
+    rv = utils.execute('./tools/generate_driver_list.py', ['docs'])
+    print(rv[0])
+

doc/source/conf.py

@@ -35,6 +35,7 @@ extensions = ['sphinx.ext.autodoc',
               'oslosphinx',
               'stevedore.sphinxext',
               'oslo_config.sphinxconfiggen',
+              'ext.cinder_driverlist',
               ]
 
 config_generator_config_file = '../../cinder/config/cinder-config-generator.conf'

doc/source/drivers.rst

@@ -1,6 +0,0 @@
-===================
- Available Drivers
-===================
-
-.. list-plugins:: oslo_messaging.notify.drivers
-    :detailed:

doc/source/index.rst

@@ -44,9 +44,20 @@ Developer Docs
    database_architecture
    scheduler-filters
    scheduler-weights
-   drivers
    oslo-middleware
 
+Drivers
+=======
+
+Cinder maintains drivers for volume backends, backup targets, and fibre
+channel zone manager fabric types. The list of the available drivers can be
+found here:
+
+.. toctree::
+   :maxdepth: 1
+
+   drivers
+
 API Extensions
 ==============
 

tools/generate_driver_list.py

@@ -15,30 +15,55 @@
 """Generate list of cinder drivers"""
 
 import os
+import sys
 
 from cinder.interface import util
 
 
-def format_description(desc):
+class Output(object):
+
+    def __init__(self, base_dir):
+        # At this point we don't care what was passed in, just a trigger
+        # to write this out to the doc tree for now
+        self.driver_file = None
+        if len(sys.argv) > 1:
+            self.driver_file = open(
+                '%s/doc/source/drivers.rst' % base_dir, 'w+')
+            self.driver_file.write('===================\n')
+            self.driver_file.write('Available Drivers\n')
+            self.driver_file.write('===================\n\n')
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, type, value, traceback):
+        self.driver_file.close()
+
+    def write(self, text):
+        if self.driver_file:
+            self.driver_file.write('%s\n' % text)
+        else:
+            print(text)
+
+
+def format_description(desc, output):
     desc = desc or '<None>'
     lines = desc.rstrip('\n').split('\n')
     for line in lines:
-        print('    %s' % line)
+        output.write('    %s' % line)
 
 
-def print_drivers(drivers, config_name):
-    # for driver in drivers.sort(key=lambda x: x.class_fqn):
+def print_drivers(drivers, config_name, output):
     for driver in sorted(drivers, key=lambda x: x.class_fqn):
-        print(driver.class_name)
-        print('-' * len(driver.class_name))
+        output.write(driver.class_name)
+        output.write('-' * len(driver.class_name))
         if driver.version:
-            print('* Version: %s' % driver.version)
-        print('* %s=%s' % (config_name, driver.class_fqn))
-        print('* Description::')
-        print('')
-        format_description(driver.desc)
-        print('')
-    print('')
+            output.write('* Version: %s' % driver.version)
+        output.write('* %s=%s' % (config_name, driver.class_fqn))
+        output.write('* Description:')
+        format_description(driver.desc, output)
+        output.write('')
+    output.write('')
 
 
 def main():
@@ -48,17 +73,18 @@ def main():
     os.chdir(cinder_root)
 
     try:
-        print('VOLUME DRIVERS')
-        print('==============')
-        print_drivers(util.get_volume_drivers(), 'volume_driver')
+        with Output(cinder_root) as output:
+            output.write('Volume Drivers')
+            output.write('==============')
+            print_drivers(util.get_volume_drivers(), 'volume_driver', output)
 
-        print('BACKUP DRIVERS')
-        print('==============')
-        print_drivers(util.get_backup_drivers(), 'backup_driver')
+            output.write('Backup Drivers')
+            output.write('==============')
+            print_drivers(util.get_backup_drivers(), 'backup_driver', output)
 
-        print('FC ZONE MANAGER DRIVERS')
-        print('=======================')
-        print_drivers(util.get_fczm_drivers(), 'zone_driver')
+            output.write('FC Zone Manager Drivers')
+            output.write('=======================')
+            print_drivers(util.get_fczm_drivers(), 'zone_driver', output)
     finally:
         os.chdir(cur_dir)
 

tox.ini

@@ -104,7 +104,8 @@ install_command = pip install -U --force-reinstall {opts} {packages}
 commands = {posargs}
 
 [testenv:docs]
-commands = python setup.py build_sphinx
+commands = 
+  python setup.py build_sphinx
 
 [testenv:gendriverlist]
 sitepackages = False