summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDoug Hellmann <doug@doughellmann.com>2017-07-20 10:54:38 -0400
committerDoug Hellmann <doug@doughellmann.com>2017-07-20 13:11:01 -0400
commitdfc70fa88e01b8c6ca1ab15a4b80bd33e87ced85 (patch)
treed713af1a1bae7edb8eb0710300bc056507df14d5
parenta98f7106e38991681b5043c31134bbae272193a2 (diff)
downloadoslo-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.py29
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,