diff options
author | Doug Hellmann <doug@doughellmann.com> | 2017-07-20 10:54:38 -0400 |
---|---|---|
committer | Doug Hellmann <doug@doughellmann.com> | 2017-07-20 13:11:01 -0400 |
commit | dfc70fa88e01b8c6ca1ab15a4b80bd33e87ced85 (patch) | |
tree | d713af1a1bae7edb8eb0710300bc056507df14d5 | |
parent | a98f7106e38991681b5043c31134bbae272193a2 (diff) | |
download | oslo-config-dfc70fa88e01b8c6ca1ab15a4b80bd33e87ced85.tar.gz |
add rst output mode for config generator4.11.0
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 <doug@doughellmann.com>
-rw-r--r-- | oslo_config/generator.py | 29 |
1 files changed, 27 insertions, 2 deletions
diff --git a/oslo_config/generator.py b/oslo_config/generator.py index 9456bda..a081d1b 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, |