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.

diff --git a/man/org.freedesktop.systemd1.xml b/man/org.freedesktop.systemd1.xml
index 24fafac272fd2bbc6be9009bfe4c8acdacce103e..1f0d1818caf320c5e8cade1d0cd6cde1c20f3c61 100644 (file)
--- a/man/org.freedesktop.systemd1.xml
+++ b/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
 

diff --git a/tools/update-dbus-docs.py b/tools/update-dbus-docs.py
index 2f69b50b89c3c98f6f0fc1f0b3c6ed6a07627220..41612947ab34758165b49f2b96e5cfb4a794ce58 100755 (executable)
--- a/tools/update-dbus-docs.py
+++ b/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