From dfc70fa88e01b8c6ca1ab15a4b80bd33e87ced85 Mon Sep 17 00:00:00 2001 From: Doug Hellmann Date: Thu, 20 Jul 2017 10:54:38 -0400 Subject: [PATCH] add rst output mode for config generator When a documentation build fails, it can be difficult to determine why. Providing RST output for the config generator will allow a contributor to look at the documentation being parsed by Sphinx to find issues. Change-Id: I4f9babc243d4a307bedd84dd4ff60f82cd16f8db Signed-off-by: Doug Hellmann --- oslo_config/generator.py | 29 +++++++++++++++++++++++++++-- 1 file changed, 27 insertions(+), 2 deletions(-) diff --git a/oslo_config/generator.py b/oslo_config/generator.py index 9456bdaa..a081d1b3 100644 --- a/oslo_config/generator.py +++ b/oslo_config/generator.py @@ -69,9 +69,11 @@ _generator_opts = [ help='Desired format for the output. "ini" is the only one which can ' 'be used directly with oslo.config. "json" and "yaml" are ' 'intended for third-party tools that want to write config files ' - 'based on the sample config data.', + 'based on the sample config data. "rst" can be used to dump ' + 'the text given to sphinx when building documentation using ' + 'the sphinx extension, for debugging.', default='ini', - choices=['ini', 'json', 'yaml'], + choices=['ini', 'json', 'yaml', 'rst'], dest='format_'), ] @@ -682,6 +684,24 @@ def _output_machine_readable(groups, output_file, conf): output_file.write('\n') +def _output_human_readable(namespaces, output_file): + """Write an RST formated version of the docs for the options. + + :param groups: A list of the namespaces to use for discovery. + :param output_file: A file-like object to which the data should be written. + """ + try: + from oslo_config import sphinxext + except ImportError: + raise RuntimeError( + 'Could not import sphinxext. ' + 'Please install Sphinx and try again.', + ) + output_data = list(sphinxext._format_option_help( + LOG, namespaces, False)) + output_file.write('\n'.join(output_data)) + + def generate(conf, output_file=None): """Generate a sample config file. @@ -711,6 +731,11 @@ def generate(conf, output_file=None): formatter.write('\n\n') _output_opts(formatter, group, group_data, conf.minimal, conf.summarize) + elif conf.format_ == 'rst': + _output_human_readable( + conf.namespace, + output_file=output_file, + ) else: _output_machine_readable(groups, output_file=output_file,