summaryrefslogtreecommitdiff
path: root/tools
diff options
context:
space:
mode:
authorJérémy Rosen <jeremy.rosen@smile.fr>2020-04-18 20:19:50 +0200
committerJérémy Rosen <jeremy.rosen@smile.fr>2020-04-20 21:03:03 +0200
commitf92c8d1c67bcdeba097e3203d8aafe3a31230ada (patch)
treeae4df5c8065f25cff04c43cd40bcc94c8a0f230a /tools
parent8906e262784bcb3989c6103803834ed35f6214d7 (diff)
downloadsystemd-f92c8d1c67bcdeba097e3203d8aafe3a31230ada.tar.gz
update-dbus-docs: automatically add variablelist for introspected items
Add a <variablelist/> tag after every programlisting we auto-generate that will be read by make-directive-index to cross-reference all dbus elements.
Diffstat (limited to 'tools')
-rwxr-xr-xtools/make-directive-index.py32
-rwxr-xr-xtools/update-dbus-docs.py49
2 files changed, 79 insertions, 2 deletions
diff --git a/tools/make-directive-index.py b/tools/make-directive-index.py
index 0333a92a1d..208528e8a1 100755
--- a/tools/make-directive-index.py
+++ b/tools/make-directive-index.py
@@ -161,6 +161,38 @@ TEMPLATE = '''\
</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' />
</refsect1>
diff --git a/tools/update-dbus-docs.py b/tools/update-dbus-docs.py
index 41612947ab..6d790bc5e3 100755
--- a/tools/update-dbus-docs.py
+++ b/tools/update-dbus-docs.py
@@ -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
@@ -212,8 +216,49 @@ 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):