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 <doug@doughellmann.com>
This commit is contained in:
parent
a98f7106e3
commit
dfc70fa88e
@ -69,9 +69,11 @@ _generator_opts = [
|
|||||||
help='Desired format for the output. "ini" is the only one which can '
|
help='Desired format for the output. "ini" is the only one which can '
|
||||||
'be used directly with oslo.config. "json" and "yaml" are '
|
'be used directly with oslo.config. "json" and "yaml" are '
|
||||||
'intended for third-party tools that want to write config files '
|
'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',
|
default='ini',
|
||||||
choices=['ini', 'json', 'yaml'],
|
choices=['ini', 'json', 'yaml', 'rst'],
|
||||||
dest='format_'),
|
dest='format_'),
|
||||||
]
|
]
|
||||||
|
|
||||||
@ -682,6 +684,24 @@ def _output_machine_readable(groups, output_file, conf):
|
|||||||
output_file.write('\n')
|
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):
|
def generate(conf, output_file=None):
|
||||||
"""Generate a sample config file.
|
"""Generate a sample config file.
|
||||||
|
|
||||||
@ -711,6 +731,11 @@ def generate(conf, output_file=None):
|
|||||||
formatter.write('\n\n')
|
formatter.write('\n\n')
|
||||||
_output_opts(formatter, group, group_data, conf.minimal,
|
_output_opts(formatter, group, group_data, conf.minimal,
|
||||||
conf.summarize)
|
conf.summarize)
|
||||||
|
elif conf.format_ == 'rst':
|
||||||
|
_output_human_readable(
|
||||||
|
conf.namespace,
|
||||||
|
output_file=output_file,
|
||||||
|
)
|
||||||
else:
|
else:
|
||||||
_output_machine_readable(groups,
|
_output_machine_readable(groups,
|
||||||
output_file=output_file,
|
output_file=output_file,
|
||||||
|
Loading…
Reference in New Issue
Block a user