Merge pull request #15476 from boucman/directive_dbus

Generate systemd.directive entries from dbus documentation

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' />
@@ -180,9 +212,10 @@ def _extract_directives(directive_groups, formatting, page):
     storopt = directive_groups['options']
     for variablelist in t.iterfind('.//variablelist'):
         klass = variablelist.attrib.get('class')
+        searchpath = variablelist.attrib.get('xpath','./varlistentry/term/varname')
         storvar = directive_groups[klass or 'miscellaneous']
         # <option>s go in OPTIONS, unless class is specified
-        for xpath, stor in (('./varlistentry/term/varname', storvar),
+        for xpath, stor in ((searchpath, storvar),
                             ('./varlistentry/term/option',
                              storvar if klass else storopt)):
             for name in variablelist.iterfind(xpath):
@@ -199,6 +232,13 @@ def _extract_directives(directive_groups, formatting, page):
                         name.tail = ''
                     name.text = text
                     formatting[text] = name
+        extra = variablelist.attrib.get('extra-ref')
+        if extra:
+            stor[extra].append((pagename, section))
+            if extra not in formatting:
+                elt = tree.Element("varname")
+                elt.text= extra
+                formatting[extra] = elt
 
     storfile = directive_groups['filenames']
     for xpath, absolute_only in (('.//refsynopsisdiv//filename', False),

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):