autohelp: generate rst tables
We are mmoving the guides to RST, so we need config-reference tables in this format. This patch adds a `rst` subcommand to autohelp.py to handle this new requirement. RST has limited tables-related features, and openstackdocstheme will need an update to improve the output. Change-Id: I5e58d60e2308d208e850f903559da5f5a6a949e3
This commit is contained in:
parent
9aa45dda9a
commit
b455d12bfb
|
@ -77,6 +77,23 @@ BASE_XML = '''<?xml version="1.0"?>
|
||||||
</table>
|
</table>
|
||||||
</para>'''
|
</para>'''
|
||||||
|
|
||||||
|
BASE_RST = '''
|
||||||
|
.. list-table:: Description of %(nice_cat)s configuration options
|
||||||
|
:header-rows: 2
|
||||||
|
:widths: 100 100
|
||||||
|
:class: config-ref-table
|
||||||
|
|
||||||
|
* - Configuration option = Default value
|
||||||
|
- Description
|
||||||
|
'''
|
||||||
|
|
||||||
|
NEW_GROUP_RST = '''
|
||||||
|
.. list-table::
|
||||||
|
:header-rows: 1
|
||||||
|
:widths: 100 100
|
||||||
|
:class: config-ref-table
|
||||||
|
|
||||||
|
'''
|
||||||
|
|
||||||
register_re = re.compile(r'''^ +.*\.register_opts\((?P<opts>[^,)]+)'''
|
register_re = re.compile(r'''^ +.*\.register_opts\((?P<opts>[^,)]+)'''
|
||||||
r'''(, (group=)?["'](?P<group>.*)["'])?\)''')
|
r'''(, (group=)?["'](?P<group>.*)["'])?\)''')
|
||||||
|
@ -385,12 +402,7 @@ def pass_through(line):
|
||||||
line.startswith('#'))
|
line.startswith('#'))
|
||||||
|
|
||||||
|
|
||||||
def write_docbook(package_name, options, target, verbose=0):
|
def _get_options_by_cat(package_name):
|
||||||
"""Write DocBook tables.
|
|
||||||
|
|
||||||
Prints a docbook-formatted table for every group of options.
|
|
||||||
"""
|
|
||||||
target = target or '../../doc/common/tables/'
|
|
||||||
options_by_cat = {}
|
options_by_cat = {}
|
||||||
|
|
||||||
with open(package_name + '.flagmappings') as f:
|
with open(package_name + '.flagmappings') as f:
|
||||||
|
@ -401,6 +413,10 @@ def write_docbook(package_name, options, target, verbose=0):
|
||||||
for category in categories.split():
|
for category in categories.split():
|
||||||
options_by_cat.setdefault(category, []).append(opt)
|
options_by_cat.setdefault(category, []).append(opt)
|
||||||
|
|
||||||
|
return options_by_cat
|
||||||
|
|
||||||
|
|
||||||
|
def _get_category_names(package_name):
|
||||||
package_headers = package_name + '.headers'
|
package_headers = package_name + '.headers'
|
||||||
category_names = {}
|
category_names = {}
|
||||||
for headers_file in ('shared.headers', package_headers):
|
for headers_file in ('shared.headers', package_headers):
|
||||||
|
@ -414,6 +430,18 @@ def write_docbook(package_name, options, target, verbose=0):
|
||||||
except IOError:
|
except IOError:
|
||||||
print("Cannot open %s (ignored)" % headers_file)
|
print("Cannot open %s (ignored)" % headers_file)
|
||||||
|
|
||||||
|
return category_names
|
||||||
|
|
||||||
|
|
||||||
|
def write_docbook(package_name, options, target, verbose=0):
|
||||||
|
"""Write DocBook tables.
|
||||||
|
|
||||||
|
Prints a docbook-formatted table for every group of options.
|
||||||
|
"""
|
||||||
|
target = target or '../../doc/common/tables/'
|
||||||
|
options_by_cat = _get_options_by_cat(package_name)
|
||||||
|
category_names = _get_category_names(package_name)
|
||||||
|
|
||||||
if not os.path.isdir(target):
|
if not os.path.isdir(target):
|
||||||
os.makedirs(target)
|
os.makedirs(target)
|
||||||
|
|
||||||
|
@ -468,6 +496,53 @@ def write_docbook(package_name, options, target, verbose=0):
|
||||||
encoding="UTF-8"))
|
encoding="UTF-8"))
|
||||||
|
|
||||||
|
|
||||||
|
def write_rst(package_name, options, target, verbose=0):
|
||||||
|
"""Write RST tables.
|
||||||
|
|
||||||
|
Prints an RST-formatted table for every group of options.
|
||||||
|
"""
|
||||||
|
target = target or '../../doc/common/tables/rst/'
|
||||||
|
options_by_cat = _get_options_by_cat(package_name)
|
||||||
|
category_names = _get_category_names(package_name)
|
||||||
|
|
||||||
|
if not os.path.isdir(target):
|
||||||
|
os.makedirs(target)
|
||||||
|
|
||||||
|
for cat in options_by_cat.keys():
|
||||||
|
if cat in category_names:
|
||||||
|
nice_cat = category_names[cat]
|
||||||
|
else:
|
||||||
|
nice_cat = cat
|
||||||
|
print("No nicename for %s" % cat)
|
||||||
|
rst_table = (BASE_RST % {'pkg': package_name,
|
||||||
|
'cat': cat,
|
||||||
|
'nice_cat': nice_cat})
|
||||||
|
curgroup = None
|
||||||
|
for optname in options_by_cat[cat]:
|
||||||
|
group, option = options.get_option(optname)
|
||||||
|
if group != curgroup:
|
||||||
|
if curgroup is not None:
|
||||||
|
rst_table += NEW_GROUP_RST
|
||||||
|
rst_table += ' * - **[%s]**\n -\n' % group
|
||||||
|
curgroup = group
|
||||||
|
|
||||||
|
if not option.help:
|
||||||
|
option.help = "No help text available for this option."
|
||||||
|
default = _sanitize_default(option)
|
||||||
|
|
||||||
|
option_text = "%s = %s" % (option.dest, default)
|
||||||
|
option_text = "``%s``" % option_text.strip()
|
||||||
|
option_help = "(%s) %s" % (type(option).__name__,
|
||||||
|
option.help.strip())
|
||||||
|
rst_table += " * - %s\n - %s\n" % (option_text, option_help)
|
||||||
|
|
||||||
|
file_path = ("%(target)s/%(package_name)s-%(cat)s.rst" %
|
||||||
|
{'target': target, 'package_name': package_name,
|
||||||
|
'cat': cat})
|
||||||
|
with open(file_path, 'w') as fd:
|
||||||
|
fd.write(rst_table)
|
||||||
|
|
||||||
|
|
||||||
def create_flagmappings(package_name, options, verbose=0):
|
def create_flagmappings(package_name, options, verbose=0):
|
||||||
"""Create a flagmappings file.
|
"""Create a flagmappings file.
|
||||||
|
|
||||||
|
@ -529,7 +604,7 @@ def main():
|
||||||
usage='%(prog)s <cmd> <package> [options]')
|
usage='%(prog)s <cmd> <package> [options]')
|
||||||
parser.add_argument('subcommand',
|
parser.add_argument('subcommand',
|
||||||
help='Action (create, update, verify, dump).',
|
help='Action (create, update, verify, dump).',
|
||||||
choices=['create', 'update', 'docbook', 'dump'])
|
choices=['create', 'update', 'docbook', 'rst', 'dump'])
|
||||||
parser.add_argument('package',
|
parser.add_argument('package',
|
||||||
help='Name of the top-level package.')
|
help='Name of the top-level package.')
|
||||||
parser.add_argument('-v', '--verbose',
|
parser.add_argument('-v', '--verbose',
|
||||||
|
@ -581,6 +656,10 @@ def main():
|
||||||
|
|
||||||
elif args.subcommand == 'docbook':
|
elif args.subcommand == 'docbook':
|
||||||
write_docbook(package_name, options, args.target, verbose=args.verbose)
|
write_docbook(package_name, options, args.target, verbose=args.verbose)
|
||||||
|
|
||||||
|
elif args.subcommand == 'rst':
|
||||||
|
write_rst(package_name, options, args.target, verbose=args.verbose)
|
||||||
|
|
||||||
elif args.subcommand == 'dump':
|
elif args.subcommand == 'dump':
|
||||||
options.dump()
|
options.dump()
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue