update-dbus-docs: add support for settings printing just one selected interface

So far the units there were being documented had only one custom interface.
But for the pid1 case, something more flexibile is needed. So let's add
an annotation in the page what we want to print, and filter in the generator.

man/org.freedesktop.systemd1.xml

@@ -625,7 +625,7 @@ node /org/freedesktop/systemd1 {
   <refsect1>
     <title>Unit Objects</title>
 
-    <programlisting>
+    <programlisting interface="org.freedesktop.systemd1.Unit">
 $ gdbus introspect --system --dest org.freedesktop.systemd1 \
       --object-path /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice
 
@@ -909,7 +909,7 @@ node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice {
     <interfacename>org.freedesktop.systemd1.Service</interfacename> interface (described here) in addition to
     the generic <interfacename>org.freedesktop.systemd1.Unit</interfacename> interface (see above).</para>
 
-    <programlisting>
+    <programlisting interface="org.freedesktop.systemd1.Service">
 $ gdbus introspect --system --dest org.freedesktop.systemd1 \
       --object-path /org/freedesktop/systemd1/unit/avahi_2ddaemon_2eservice
 
@@ -1120,7 +1120,7 @@ $ gdbus introspect --system --dest org.freedesktop.systemd1 \
   <refsect1>
     <title>Socket Unit Objects</title>
 
-    <programlisting>
+    <programlisting interface="org.freedesktop.systemd1.Socket">
 $ gdbus introspect --system --dest org.freedesktop.systemd1 \
       --object-path /org/freedesktop/systemd1/unit/avahi_2ddaemon_2esocket
 
@@ -1288,7 +1288,7 @@ node /org/freedesktop/systemd1/unit/avahi_2ddaemon_2esocket {
   <refsect1>
     <title>Target Unit Objects</title>
 
-    <programlisting>
+    <programlisting interface="org.freedesktop.systemd1.Target">
 $ gdbus introspect --system --dest org.freedesktop.systemd1 \
       --object-path /org/freedesktop/systemd1/unit/basic_2etarget
 
@@ -1323,11 +1323,11 @@ node /org/freedesktop/systemd1/unit/basic_2etarget {
     <para>All device unit objects implement the <interfacename>org.freedesktop.systemd1.Device</interfacename> interface (described here)
     in addition to the generic <interfacename>org.freedesktop.systemd1.Unit</interfacename> interface (see above).</para>
 
-    <programlisting>
+    <programlisting interface="org.freedesktop.systemd1.Device">
 $ gdbus introspect --system --dest org.freedesktop.systemd1 \
-      --object-path /org/freedesktop/systemd1/unit/dev_2ddisk_2dby_5cx2did_2data_5cx2dSAMSUNG_5fHD501LJ_5fS0MUJ1KQ161445_2edevice
+      --object-path /org/freedesktop/systemd1/unit/dev_2dfoo_2edevice
 
-node /org/freedesktop/systemd1/unit/dev_2ddisk_2dby_5cx2did_2data_5cx2dSAMSUNG_5fHD501LJ_5fS0MUJ1KQ161445_2edevice {
+node /org/freedesktop/systemd1/unit/dev_2d_foo_2edevice {
   interface org.freedesktop.systemd1.Unit {
     ...
   };
@@ -1367,7 +1367,7 @@ node /org/freedesktop/systemd1/unit/dev_2ddisk_2dby_5cx2did_2data_5cx2dSAMSUNG_5
     interface (described here) in addition to the generic
     <interfacename>org.freedesktop.systemd1.Unit</interfacename> interface (see above)</para>
 
-    <programlisting>
+    <programlisting interface="org.freedesktop.systemd1.Mount">
 $ gdbus introspect --system --dest org.freedesktop.systemd1 \
       --object-path /org/freedesktop/systemd1/unit/home_2emount
 
@@ -1507,7 +1507,7 @@ node /org/freedesktop/systemd1/unit/home_2emount {
     <interfacename>org.freedesktop.systemd1.Automount</interfacename> interface (described here) in addition
     to the generic <interfacename>org.freedesktop.systemd1.Unit</interfacename> interface (see above).</para>
 
-    <programlisting>
+    <programlisting interface="org.freedesktop.systemd1.Automount">
 $ gdbus introspect --system --dest org.freedesktop.systemd1 \
       --object-path /org/freedesktop/systemd1/unit/proc_2dsys_2dfs_2dbinfmt_5fmisc_2eautomount
 
@@ -1555,7 +1555,7 @@ node /org/freedesktop/systemd1/unit/proc_2dsys_2dfs_2dbinfmt_5fmisc_2eautomount
     interface (described here) in addition to the generic
     <interfacename>org.freedesktop.systemd1.Unit</interfacename> interface (see above).</para>
 
-    <programlisting>
+    <programlisting interface="org.freedesktop.systemd1.Timer">
 $ gdbus introspect --system --dest org.freedesktop.systemd1 \
       --object-path /org/freedesktop/systemd1/unit/systemd_2dtmpfiles_2dclean_2etimer
 
@@ -1622,7 +1622,7 @@ node /org/freedesktop/systemd1/unit/systemd_2dtmpfiles_2dclean_2etimer {
     interface (described here) in addition to the generic
     <interfacename>org.freedesktop.systemd1.Unit</interfacename> interface (see above).</para>
 
-    <programlisting>
+    <programlisting interface="org.freedesktop.systemd1.Swap">
 $ gdbus introspect --system --dest org.freedesktop.systemd1 \
       --object-path /org/freedesktop/systemd1/unit/dev_2dsda3_2eswap
 
@@ -1760,7 +1760,7 @@ node /org/freedesktop/systemd1/unit/dev_2dsda3_2eswap {
   <refsect1>
     <title>Path Unit Objects</title>
 
-    <programlisting>
+    <programlisting interface="org.freedesktop.systemd1.Path">
 $ gdbus introspect --system --dest org.freedesktop.systemd1 \
       --object-path /org/freedesktop/systemd1/unit/cups_2epath
 
@@ -1816,7 +1816,7 @@ node /org/freedesktop/systemd1/unit/cups_2epath {
     interface (described here) in addition to the generic
     <interfacename>org.freedesktop.systemd1.Unit</interfacename> interface (see above).</para>
 
-    <programlisting>
+    <programlisting interface="org.freedesktop.systemd1.Slice">
 $ gdbus introspect --system --dest org.freedesktop.systemd1 \
       --object-path /org/freedesktop/systemd1/unit/system_2eslice
 
@@ -1868,7 +1868,7 @@ node /org/freedesktop/systemd1/unit/system_2eslice {
     interface (described here) in addition to the generic
     <interfacename>org.freedesktop.systemd1.Unit</interfacename> interface (see above).</para>
 
-    <programlisting>
+    <programlisting interface="org.freedesktop.systemd1.Scope">
 $ gdbus introspect --system --dest org.freedesktop.systemd1 \
       --object-path /org/freedesktop/systemd1/unit/session_2d1_2escope
 

tools/update-dbus-docs.py

@@ -99,12 +99,15 @@ def print_property(declarations, elem, *, prefix, file):
     access = ACCESS_MAP.get(access, access)
     print(f'''{prefix}{access} {type} {name} = {value_ellipsis(type)};''', file=file)
 
-def print_interface(iface, *, prefix, file, print_boring, declarations):
+def print_interface(iface, *, prefix, file, print_boring, only_interface, declarations):
     name = iface.get('name')
 
-    is_boring = name in BORING_INTERFACES
+    is_boring = (name in BORING_INTERFACES or
+                 only_interface is not None and name != only_interface)
+
     if is_boring and print_boring:
         print(f'''{prefix}interface {name} {{ ... }};''', file=file)
+
     elif not is_boring and not print_boring:
         print(f'''{prefix}interface {name} {{''', file=file)
         prefix2 = prefix + '  '
@@ -157,7 +160,7 @@ def check_documented(document, declarations):
 
     return missing
 
-def xml_to_text(destination, xml):
+def xml_to_text(destination, xml, *, only_interface=None):
     file = io.StringIO()
 
     declarations = collections.defaultdict(list)
@@ -168,6 +171,7 @@ def xml_to_text(destination, xml):
         for iface in xml.findall('./interface'):
             print_interface(iface, prefix='  ', file=file,
                             print_boring=print_boring,
+                            only_interface=only_interface,
                             declarations=declarations)
 
     print(f'''}};''', file=file)
@@ -180,6 +184,8 @@ def subst_output(document, programlisting):
     except NoCommand:
         return
 
+    only_interface = programlisting.get('interface', None)
+
     argv = shlex.split(cmd)
     argv += ['--xml']
     print(f'COMMAND: {shlex.join(argv)}')
@@ -195,7 +201,7 @@ def subst_output(document, programlisting):
 
     xml = etree.fromstring(out, parser=PARSER)
 
-    new_text, declarations = xml_to_text(object_path, xml)
+    new_text, declarations = xml_to_text(object_path, xml, only_interface=only_interface)
 
     programlisting.text = '\n'.join(prefix_lines) + '\n' + new_text + footer