colin/NetworkManager
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: merge settings docs in a separate step

Browse Source 
The script "libnm/generate-setting-docs.py" generates property info based
on GObject introspection data.

Optionally, when creating the manual for D-Bus documentation, it would accept
an argument "--override" to merge the generated information with the information
from an XML generated by "libnm/generate-plugin-docs.xml". Change this.
Instead, let "libnm/generate-setting-docs.py" just do one thing: generate
the XML based on GObject introspection data. Then, a second script
"libnm/generate-docs-nm-settings-docs-merge.py" can merge the XMLs.

Note that currently the manual for "nm-settings-keyfile" only contains
information about properties that are explicitly mentioned for keyfile.
It think that is not right. In NetworkManager there are multiple "aspects"
about connection profiles: D-Bus, libnm, nmcli, keyfile and ifcfg-rh.
When we generate a manual page for any of these aspects, we should always
detail all properties. At least for nmcli and D-Bus. That means, we will
do the merging multiple times. Hence, keep the steps for parsing GObject
introspection data and the merging separate.

Also, "generate-setting-docs.py" and "generate-plugin-docs.pl" should
generate the same XML scheme, so that merge doesn't need special hacks.
That is currently not the case, for example, the override XML contains a
"format" attribute, while the other one contains a "type". Merging these
is a special hack. This should be unified.
This commit is contained in:
Thomas Haller
2020-05-28 10:19:21 +02:00
parent 08f15d49a2
commit 2f78a824d8
4 changed files with 181 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files

51
libnm/generate-setting-docs.py
View File

@@ -172,7 +172,6 @@ def usage():
parser = argparse.ArgumentParser()
parser.add_argument('-l', '--lib-path', metavar='PATH', action='append', help='path to scan for shared libraries')
parser.add_argument('-g', '--gir', metavar='FILE', help='NM-1.0.gir file')
parser.add_argument('-x', '--overrides', metavar='FILE', help='documentation overrides file')
parser.add_argument('-o', '--output', metavar='FILE', help='output file')
args = parser.parse_args()
@@ -195,9 +194,6 @@ settings = sorted(settings, key=settings_sort_key)
init_constants(girxml, settings)
if args.overrides is not None:
overrides = ET.parse(args.overrides).getroot()
outfile.write("""<?xml version=\"1.0\"?>
<!DOCTYPE nm-setting-docs [
<!ENTITY quot "&#34;">
@@ -218,48 +214,31 @@ for settingxml in settings:
outfile.write(" <setting name=\"%s\" description=\"%s\" name_upper=\"%s\" >\n" % (setting.props.name, class_desc, get_setting_name_define (settingxml)))
setting_properties = { prop.name: prop for prop in GObject.list_properties(setting) if prop.name != 'name' }
if args.overrides is None:
setting_overrides = {}
else:
setting_overrides = { override.attrib['name']: override for override in overrides.findall('./setting[@name="%s"]/property' % setting.props.name) }
properties = sorted(set.union(set(setting_properties.keys()), set(setting_overrides.keys())))
for prop in sorted(setting_properties):
pspec = setting_properties[prop]
for prop in properties:
value_type = None
value_desc = None
default_value = None
propxml = settingxml.find('./gi:property[@name="%s"]' % pspec.name, ns_map)
if propxml is None:
propxml = basexml.find('./gi:property[@name="%s"]' % pspec.name, ns_map)
if propxml is None:
propxml = ipxml.find('./gi:property[@name="%s"]' % pspec.name, ns_map)
if prop in setting_properties:
pspec = setting_properties[prop]
propxml = settingxml.find('./gi:property[@name="%s"]' % pspec.name, ns_map)
if propxml is None:
propxml = basexml.find('./gi:property[@name="%s"]' % pspec.name, ns_map)
if propxml is None:
propxml = ipxml.find('./gi:property[@name="%s"]' % pspec.name, ns_map)
value_type = get_prop_type(setting, pspec)
value_desc = get_docs(propxml)
default_value = get_default_value(setting, pspec, propxml)
if prop in setting_overrides:
override = setting_overrides[prop]
if override.attrib['format'] != '':
value_type = override.attrib['format']
if override.attrib['description'] != '':
value_desc = override.attrib['description']
value_type = get_prop_type(setting, pspec)
value_desc = get_docs(propxml)
default_value = get_default_value(setting, pspec, propxml)
prop_upper = prop.upper().replace('-', '_')
if value_desc is None:
raise Exception("%s.%s needs a documentation description" % (setting.props.name, prop))
default_value_as_xml = ''
if default_value is not None:
outfile.write(" <property name=\"%s\" name_upper=\"%s\" type=\"%s\" default=\"%s\" description=\"%s\" />\n" %
(prop, prop_upper, value_type, escape(default_value), escape(value_desc)))
else:
outfile.write(" <property name=\"%s\" name_upper=\"%s\" type=\"%s\" description=\"%s\" />\n" %
(prop, prop_upper, value_type, escape(value_desc)))
default_value_as_xml = (' default=\"%s\"' % (escape(default_value)))
outfile.write(" <property name=\"%s\" name_upper=\"%s\" type=\"%s\"%s description=\"%s\" />\n" %
(prop, prop_upper, value_type, default_value_as_xml, escape(value_desc)))
outfile.write(" </setting>\n")