shaba/systemd-stable
1
1
Fork 0
mirror of https://github.com/systemd/systemd-stable.git synced 2024-12-22 13:33:56 +03:00
Code

update-dbus-docs: automatically add variablelist for introspected items

Browse Source 
Add a <variablelist/> tag after every programlisting we auto-generate that
will be read by make-directive-index to cross-reference all dbus elements.
This commit is contained in:
Jérémy Rosen 2020-04-18 20:19:50 +02:00
parent 8906e26278
commit f92c8d1c67
2 changed files with 79 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

32
tools/make-directive-index.py
View File

@ -160,6 +160,38 @@ TEMPLATE = '''\
<variablelist id='filenames' />
</refsect1>
<refsect1>
<title>D-Bus interfaces</title>
<para>Interaces exposed over D-Bus.</para>
<variablelist id='dbus-interface' />
</refsect1>
<refsect1>
<title>D-Bus methods</title>
<para>Methods exposed in the D-Bus interface.</para>
<variablelist id='dbus-method' />
</refsect1>
<refsect1>
<title>D-Bus properties</title>
<para>Properties exposed in the D-Bus interface.</para>
<variablelist id='dbus-property' />
</refsect1>
<refsect1>
<title>D-Bus signals</title>
<para>Signals emitted in the D-Bus interface.</para>
<variablelist id='dbus-signal' />
</refsect1>
<refsect1>
<title>Colophon</title>
<para id='colophon' />

49
tools/update-dbus-docs.py
View File

@ -164,6 +164,7 @@ def xml_to_text(destination, xml, *, only_interface=None):
file = io.StringIO()
declarations = collections.defaultdict(list)
interfaces = []
print(f'''node {destination} {{''', file=file)
@ -173,10 +174,13 @@ def xml_to_text(destination, xml, *, only_interface=None):
print_boring=print_boring,
only_interface=only_interface,
declarations=declarations)
name = iface.get('name')
if not name in BORING_INTERFACES:
interfaces.append(name)
print(f'''}};''', file=file)
return file.getvalue(), declarations
return file.getvalue(), declarations, interfaces
def subst_output(document, programlisting):
try:
@ -201,7 +205,7 @@ def subst_output(document, programlisting):
xml = etree.fromstring(out, parser=PARSER)
new_text, declarations = xml_to_text(object_path, xml, only_interface=only_interface)
new_text, declarations, interfaces = xml_to_text(object_path, xml, only_interface=only_interface)
programlisting.text = '\n'.join(prefix_lines) + '\n' + new_text + footer
@ -211,9 +215,50 @@ def subst_output(document, programlisting):
# delete old comments
for child in parent:
if (child.tag == etree.Comment
and 'Autogenerated' in child.text):
parent.remove(child)
if (child.tag == etree.Comment
and 'not documented' in child.text):
parent.remove(child)
if (child.tag == "variablelist"
and child.attrib.get("generated",False) == "True"):
parent.remove(child)
# insert pointer for systemd-directives generation
the_tail = programlisting.tail #tail is erased by addnext, so save it here.
prev_element = etree.Comment("Autogenerated cross-references for systemd.directives, do not edit")
programlisting.addnext(prev_element)
programlisting.tail = the_tail
for interface in interfaces:
variablelist = etree.Element("variablelist")
variablelist.attrib['class'] = 'dbus-interface'
variablelist.attrib['generated'] = 'True'
variablelist.attrib['extra-ref'] = interface
prev_element.addnext(variablelist)
prev_element.tail = the_tail
prev_element = variablelist
for decl_type,decl_list in declarations.items():
for declaration in decl_list:
variablelist = etree.Element("variablelist")
variablelist.attrib['class'] = 'dbus-'+decl_type
variablelist.attrib['generated'] = 'True'
if decl_type == 'method' :
variablelist.attrib['extra-ref'] = declaration + '()'
else:
variablelist.attrib['extra-ref'] = declaration
prev_element.addnext(variablelist)
prev_element.tail = the_tail
prev_element = variablelist
last_element = etree.Comment("End of Autogenerated section")
prev_element.addnext(last_element)
prev_element.tail = the_tail
last_element.tail = the_tail
# insert comments for undocumented items
for item in reversed(missing):