diff --git a/.gitignore b/.gitignore index 94f86288534..b724864efdc 100644 --- a/.gitignore +++ b/.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 diff --git a/doc/ext/cinder_driverlist.py b/doc/ext/cinder_driverlist.py new file mode 100644 index 00000000000..5a7a6192650 --- /dev/null +++ b/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]) + diff --git a/doc/source/conf.py b/doc/source/conf.py index f70900170d8..d763fe9e962 100644 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -36,6 +36,7 @@ extensions = ['sphinx.ext.autodoc', 'oslosphinx', 'stevedore.sphinxext', 'oslo_config.sphinxconfiggen', + 'ext.cinder_driverlist', ] config_generator_config_file = '../../cinder/config/cinder-config-generator.conf' diff --git a/doc/source/drivers.rst b/doc/source/drivers.rst deleted file mode 100644 index 44ee4c2ab3c..00000000000 --- a/doc/source/drivers.rst +++ /dev/null @@ -1,6 +0,0 @@ -=================== - Available Drivers -=================== - -.. list-plugins:: oslo_messaging.notify.drivers - :detailed: diff --git a/doc/source/index.rst b/doc/source/index.rst index 0fee7585e1d..dff96cce131 100644 --- a/doc/source/index.rst +++ b/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 ============== diff --git a/tools/generate_driver_list.py b/tools/generate_driver_list.py index ece213c9ce7..2cb8701e416 100755 --- a/tools/generate_driver_list.py +++ b/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 '' 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) diff --git a/tox.ini b/tox.ini index a5e5389154d..8f85ccd5273 100644 --- a/tox.ini +++ b/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