Merge "Make flagmapping optional"

This commit is contained in:
Jenkins 2017-03-21 22:37:47 +00:00 committed by Gerrit Code Review
commit 3a47ece53b
4 changed files with 98 additions and 15 deletions

View File

@ -75,9 +75,12 @@ names as arguments:
Flagmappings files
------------------
The flagmappings files use the following format:
::
The tool uses flagmapping files to map options to custom categories. Flag
mapping files can be found in the ``tools/autogenerate-config-flagmappings``
folder of the openstack-manuals project. Not all projects use flagmapping
files, as those that do not will be disabled by the presence of a
``$project.disable`` file in that folder. For those that do, however, the files
use the following format::
OPTION_SECTION/OPTION_NAME group1 [group2, ...]

View File

@ -396,6 +396,10 @@ class OptionsCache(object):
return cmp(x, y)
def _use_categories(package_name):
return not os.path.isfile(package_name + '.disable')
def pass_through(line):
"""Whether to ignore the line."""
return (not line.strip() or
@ -478,19 +482,29 @@ def _format_opt(option):
def write_files(package_name, options, target):
"""Write tables.
Prints a table for every group of options.
Some projects make use of flagmapping files, while others make use
of oslo.config's OptGroup to do the same in code. The function will
handle both, printing a list of options by either category or group.
"""
target = target or '../../doc/config-reference/source/tables'
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)
if _use_categories(package_name):
_write_files_by_category(package_name, options, target)
else:
_write_files_by_group(package_name, options, target)
def _write_files_by_category(package_name, options, target):
options_by_cat = _get_options_by_cat(package_name)
category_names = _get_category_names(package_name)
for cat in options_by_cat.keys():
env = {
'pkg': package_name,
'cat': cat,
'label': '-'.join([package_name, cat]),
'groups': [],
'items': [],
}
@ -522,19 +536,42 @@ def write_files(package_name, options, target):
items.append(_format_opt(option))
env['items'].append(items)
env['table_label'] = package_name + '-' + cat
file_path = ("%(target)s/%(package_name)s-%(cat)s.rst" %
{'target': target, 'package_name': package_name,
'cat': cat})
tmpl_file = os.path.join(os.path.dirname(__file__),
'templates/autohelp.rst.j2')
with open(tmpl_file) as fd:
template = jinja2.Template(fd.read(), trim_blocks=True)
output = template.render(filename=file_path, **env)
'templates/autohelp-category.rst.j2')
_write_template(tmpl_file, file_path, env)
with open(file_path, 'w') as fd:
fd.write(output)
def _write_files_by_group(package_name, options, target):
for group in options.get_group_names():
env = {
'pkg': package_name,
'group': group,
'label': '-'.join([package_name, group]),
'items': [],
}
for option in options.get_group(group):
env['items'].append(_format_opt(option))
file_path = ("%(target)s/%(package_name)s-%(group)s.rst" %
{'target': target, 'package_name': package_name,
'group': group})
tmpl_file = os.path.join(os.path.dirname(__file__),
'templates/autohelp-group.rst.j2')
_write_template(tmpl_file, file_path, env)
def _write_template(template_path, output_path, env):
with open(template_path) as fd:
template = jinja2.Template(fd.read(), trim_blocks=True)
output = template.render(filename=output_path, **env)
with open(output_path, 'w') as fd:
fd.write(output)
def update_flagmappings(package_name, options, verbose=0):
@ -544,6 +581,9 @@ def update_flagmappings(package_name, options, verbose=0):
This will create a new file $package_name.flagmappings.new with
category information merged from the existing $package_name.flagmappings.
"""
if not _use_categories:
print("This project does not use flagmappings. Nothing to update.")
original_flags = {}
try:
with open(package_name + '.flagmappings') as f:

View File

@ -8,7 +8,7 @@
autogenerate-config-doc tool from the openstack-doc-tools repository, or
ask for help on the documentation mailing list, IRC channel or meeting.
.. _{{ table_label }}:
.. _{{ label }}:
.. list-table:: Description of {{ nice_cat }} configuration options
:header-rows: 1

View File

@ -0,0 +1,40 @@
..
Warning: Do not edit this file. It is automatically generated from the
software project's code and your changes will be overwritten.
The tool to generate this file lives in openstack-doc-tools repository.
Please make any changes needed in the code, then run the
autogenerate-config-doc tool from the openstack-doc-tools repository, or
ask for help on the documentation mailing list, IRC channel or meeting.
.. _{{ label }}:
.. list-table:: Description of {{ group }} configuration options
:header-rows: 1
:class: config-ref-table
* - Configuration option = Default value
- Description
{% for item in items %}
{% if item[2] is equalto '' %}
* - ``{{ item[0] }}`` =
{% else %}
* - ``{{ item[0] }}`` = ``{{ item[2] }}``
{% endif %}
{% for paragraph in item[3] %}
{% if loop.first %}
- ({{ item [1] }}) {{ paragraph }}
{% else %}
{{ paragraph }}
{% endif %}
{% endfor %}
{% for flagname, flagdesc in item[4] %}
- **{{ flagname }}**
{{ flagdesc }}
{% endfor %}
{% endfor %}