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.

diff --git a/tools/make-directive-index.py b/tools/make-directive-index.py
index 0333a92a1d92d6f0df3bbb0ad1d4f3f45e2a6cd0..208528e8a145d463b5ea7a2dfabdcc6017f4f1a6 100755 (executable)
--- a/tools/make-directive-index.py
+++ b/tools/make-directive-index.py
@@ -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' />

diff --git a/tools/update-dbus-docs.py b/tools/update-dbus-docs.py
index 41612947ab34758165b49f2b96e5cfb4a794ce58..6d790bc5e314aca27d378b3904c989861e8eaf78 100755 (executable)
--- 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
 
@@ -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):