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

boucman · boucman · commit f92c8d1c67bc · 2020-04-20T21:03:03.000+02:00
Add a &lt;variablelist/&gt; 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
@@ -160,6 +160,38 @@
                 <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
@@ -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):
