Make swift config tables the source of truth
As discussed on the mailing list, this patch will make the swift configuration tables found in common a source of truth for the helptext. The script that generates them has been updated for this, and will now only add/remove options, update default values, and replace helptext where it does not exist in the tables. Another run of the script was done and tables were updated. Backstory: All projects other than Swift use OpenStack Common for configuration, and define option, default value and help text in the code in a way that it's possible to extract. Since the code is able to act in this way, we can stop maintaining separate instructive lines for configuration options, and instead fix any text problems in the code itself. This both improves the quality of the code and fixes our double maintenance problem. For swift, we needed a different approach. Unfortunately, I think we don't have the ability to treat the code as the definitive source and move all maintenance there. The lack of instruction for every option, and absence of structure precludes this. So I wrote some nasty scraping things (from RST and sample conf file) to seed an initial list of configuration options. My plan from here was to make the 'update' portion of the script treat the textual descriptions in common/tables/swift-*.xml as definitive. The script would still search the swift code to add or remove options, so we could guarantee completeness, and after an initial push to write out proper help text the maintenance becomes far simpler. Change-Id: I2464f5c63cb0da110e1871a09a59380dad9b6b27
This commit is contained in:
Tom Fifield
parent
19220c93a1
commit
322892f4dd
|
|
@ -12,6 +12,7 @@ from xml.sax.saxutils import escape
|
|||
# and generally only having a single entry
|
||||
# after the equals (the default value)
|
||||
|
||||
|
||||
def parse_line(line):
|
||||
"""
|
||||
takes a line from a swift sample configuration file and attempts
|
||||
|
|
@ -32,26 +33,33 @@ def parse_line(line):
|
|||
return None
|
||||
return config, default.strip()
|
||||
|
||||
def get_existing_options(optfile):
|
||||
|
||||
def get_existing_options(optfiles):
|
||||
"""
|
||||
parses an existing XML table to compile a list of existing options
|
||||
"""
|
||||
options = []
|
||||
xmldoc = minidom.parse(optfile)
|
||||
tdlist = xmldoc.getElementsByTagName('td')
|
||||
for td in tdlist:
|
||||
try:
|
||||
tdvalue = td.childNodes[0].nodeValue
|
||||
except IndexError:
|
||||
continue
|
||||
if '=' in tdvalue and ' ' not in tdvalue:
|
||||
options.append(tdvalue.split('=',1)[0])
|
||||
options = {}
|
||||
for optfile in optfiles:
|
||||
xmldoc = minidom.parse(optfile)
|
||||
tbody = xmldoc.getElementsByTagName('tbody')[0]
|
||||
trlist = tbody.getElementsByTagName('tr')
|
||||
for tr in trlist:
|
||||
try:
|
||||
optentry = tr.childNodes[1].childNodes[0]
|
||||
option, default = optentry.nodeValue.split('=', 1)
|
||||
helptext = tr.childNodes[2].childNodes[0].nodeValue
|
||||
except IndexError:
|
||||
continue
|
||||
if option not in options or 'No help text' in options[option]:
|
||||
#options[option.split('=',1)[0]] = helptext
|
||||
options[option] = helptext
|
||||
return options
|
||||
|
||||
|
||||
def extract_descriptions_from_devref(repo, options):
|
||||
"""
|
||||
loop through the devref RST files, looking for lines formatted
|
||||
such that they might contain a description of a particular
|
||||
such that they might contain a description of a particular
|
||||
option
|
||||
"""
|
||||
option_descs = {}
|
||||
|
|
@ -68,29 +76,31 @@ def extract_descriptions_from_devref(repo, options):
|
|||
in_option_block = False
|
||||
continue
|
||||
if line[0] == ' ' and prev_option is not None:
|
||||
option_descs[prev_option] = option_descs[prev_option] + ' ' + line.strip()
|
||||
option_descs[prev_option] = (option_descs[prev_option]
|
||||
+ ' ' + line.strip())
|
||||
for option in options:
|
||||
line_parts = line.strip().split(None, 2)
|
||||
if (' ' in line and len(line_parts) == 3
|
||||
and option == line_parts[0]
|
||||
and line_parts[1] != '=' and option != 'use'
|
||||
and (option not in option_descs or
|
||||
and (option not in option_descs or
|
||||
len(option_descs[option]) < len(line_parts[2]))):
|
||||
option_descs[option] = line_parts[2]
|
||||
prev_option = option
|
||||
return option_descs
|
||||
|
||||
|
||||
def new_section_file(sample, current_section):
|
||||
section_filename = ('swift-' +
|
||||
path.basename(sample).split('.conf')[0]
|
||||
+ '-' + current_section.replace('[','').replace(']','').replace(':','-')
|
||||
+ '-'
|
||||
+ current_section.replace('[', '').replace(']', '').replace(':', '-')
|
||||
+ '.xml')
|
||||
section_file = open(section_filename, 'w')
|
||||
section_file.write('<?xml version="1.0" encoding="UTF-8"?>\n\
|
||||
<!-- Warning: Do not edit this file. It is automatically\n\
|
||||
generated and your changes will be overwritten.\n\
|
||||
The tool to do so lives in the tools directory of this\n\
|
||||
repository -->\n\
|
||||
<!-- The tool that generated this table lives in the\n\
|
||||
tools directory of this repository. As it was a one-time\n\
|
||||
generation, you can edit this file. -->\n\
|
||||
<para xmlns="http://docbook.org/ns/docbook" version="5.0">\n\
|
||||
<table rules="all">\n\
|
||||
<caption>Description of configuration options for <literal>'
|
||||
|
|
@ -107,66 +117,75 @@ def new_section_file(sample, current_section):
|
|||
<tbody>')
|
||||
return section_file
|
||||
|
||||
def create_new_tables(repo, vebose, existing_options=None):
|
||||
|
||||
def create_new_tables(repo, verbose):
|
||||
"""
|
||||
writes a set of docbook-formatted tables, one per section in swift
|
||||
configuration files. Uses existing tables and swift devref as a source
|
||||
of truth in that order to determine helptext for options found in
|
||||
sample config files
|
||||
"""
|
||||
existing_tables = glob.glob('../../doc/src/docbkx/common/tables/swift*xml')
|
||||
options = []
|
||||
for table in existing_tables:
|
||||
options.extend(get_existing_options(table))
|
||||
options = {}
|
||||
#use the existing tables to get a list of option names
|
||||
options = get_existing_options(existing_tables)
|
||||
option_descs = extract_descriptions_from_devref(repo, options)
|
||||
conf_samples = glob.glob(repo + '/etc/*conf-sample')
|
||||
conf_samples = glob.glob(repo + '/etc/*conf-sample')
|
||||
for sample in conf_samples:
|
||||
current_section = None
|
||||
section_file = None
|
||||
sample_file = open(sample,'r')
|
||||
sample_file = open(sample, 'r')
|
||||
for line in sample_file:
|
||||
if '[' in line and ']\n' in line and '=' not in line:
|
||||
#header line
|
||||
"""
|
||||
it's a header line in the conf file, open a new table file
|
||||
for this section and close any existing one
|
||||
"""
|
||||
if current_section != line.strip('#').strip():
|
||||
if section_file is not None:
|
||||
section_file.write('\n </tbody>\n\
|
||||
</table>\n\
|
||||
</para>')
|
||||
section_file.close()
|
||||
current_section = line.strip('#').strip()
|
||||
current_section = line.strip('#').strip()
|
||||
section_file = new_section_file(sample, current_section)
|
||||
elif section_file is not None:
|
||||
#config option line
|
||||
"""
|
||||
it's a config option line in the conf file, find out the
|
||||
help text and write to the table file.
|
||||
"""
|
||||
parsed_line = parse_line(line)
|
||||
if parsed_line is not None:
|
||||
if parsed_line[0] in option_descs:
|
||||
option_desc = option_descs[parsed_line[0]]
|
||||
if (parsed_line[0] in options.keys()
|
||||
and 'No help text' not in options[parsed_line[0]]):
|
||||
# use the help text from existing tables
|
||||
option_desc = options[parsed_line[0]].replace(u'\xa0', u' ')
|
||||
elif parsed_line[0] in option_descs:
|
||||
# use the help text from the devref
|
||||
option_desc = option_descs[parsed_line[0]].replace(u'\xa0', u' ')
|
||||
else:
|
||||
option_desc = 'No help text available for this option'
|
||||
#if (existing_options is not None
|
||||
# and parsed_line[0] not in existing_options):
|
||||
# print "New Option: " + parsed_line[0]
|
||||
#elif existing_options is not None:
|
||||
# existing_options.remove(parsed_line[0])
|
||||
if verbose > 0:
|
||||
print parsed_line[0] + "has no help text"
|
||||
section_file.write('\n <tr>\n\
|
||||
<td>' + parsed_line[0] + '=' + escape(str(parsed_line[1])) +
|
||||
'</td><td>'+ option_desc + '</td>\n' + ' </tr>')
|
||||
<td>' + parsed_line[0] + '=' +
|
||||
escape(str(parsed_line[1])) +
|
||||
'</td><td>' + option_desc + '</td>\n' +
|
||||
' </tr>')
|
||||
if section_file is not None:
|
||||
section_file.write('\n </tbody>\n\
|
||||
</table>\n\
|
||||
</para>')
|
||||
section_file.close()
|
||||
#print "Removed: " + str(existing_options)
|
||||
|
||||
|
||||
def main(repo, verbose=0):
|
||||
"""
|
||||
writes a set of docbook-formatted files, based on configuration sections
|
||||
in swift sample configuration files
|
||||
actions: new - creates blank configuration files
|
||||
update - creates updated configuration files based on existing ones
|
||||
"""
|
||||
action = 'create'
|
||||
#action = 'update'
|
||||
|
||||
if action == "create":
|
||||
create_new_tables(repo, verbose)
|
||||
elif action == "update":
|
||||
options = get_existing_options('/home/fifieldt/temp/os-doc-on-a-plane-2/doc/src/docbkx/common/tables/swift-object-server-[DEFAULT].xml')
|
||||
create_new_tables(repo, verbose, options)
|
||||
create_new_tables(repo, verbose)
|
||||
|
||||
if __name__ == "__main__":
|
||||
main(sys.argv[1])
|
||||
|
|
|
|||
Loading…
Reference in New Issue