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:
parent
88ae9f08ac
commit
d962670652
|
@ -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, ...]
|
||||
|
||||
|
|
|
@ -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:
|
||||
|
|
|
@ -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
|
|
@ -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 %}
|
Loading…
Reference in New Issue