From 8148038e92280d088e33106adc8367b8250ee025 Mon Sep 17 00:00:00 2001 From: Sean McGinnis Date: Sat, 23 Jul 2016 12:13:34 -0500 Subject: [PATCH] Add driver list to doc build We have tox -e gendriverlist that outputs an RST-ish report of all drivers in the tree. This output can be used in the docs build to automatically publish the list of drivers to make it easier to find officially supported drivers. This effectively removes the existing drivers.html that was generated prior that did not actually contain any useful information. Change-Id: I8de78723af76aabcc976733ac4b248db0b8ca16f --- .gitignore | 1 + doc/ext/cinder_driverlist.py | 24 ++++++++++++ doc/source/conf.py | 1 + doc/source/drivers.rst | 6 --- doc/source/index.rst | 13 ++++++- tools/generate_driver_list.py | 70 ++++++++++++++++++++++++----------- tox.ini | 3 +- 7 files changed, 88 insertions(+), 30 deletions(-) create mode 100644 doc/ext/cinder_driverlist.py delete mode 100644 doc/source/drivers.rst 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