Make flagmapping optional

Support for flagmappings was useful in the days before OptGroup was
available. Today, it's mostly a burden and not necessary for projects
such as nova. Make this feature optional, allowing us to make use of
built-in oslo.config where available.

The actual flagmapping files themselves are found in another project and
cannot be removed here. This will be done in a separate change.

Change-Id: I27296954ad8ce2010fc464ad81c8da4859ba2531
This commit is contained in:
Stephen Finucane 2017-03-09 15:10:08 +00:00
parent 88ae9f08ac
commit d962670652
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 %}