tools/update-dbus-docs.py

   1 #!/usr/bin/env python3
   2 # SPDX-License-Identifier: LGPL-2.1+
   3
   4 import collections
   5 import sys
   6 import shlex
   7 import subprocess
   8 import io
   9 import pprint
  10 from lxml import etree
  11
  12 PARSER = etree.XMLParser(no_network=True,
  13                          remove_comments=False,
  14                          strip_cdata=False,
  15                          resolve_entities=False)
  16
  17 PRINT_ERRORS = True
  18
  19 class NoCommand(Exception):
  20     pass
  21
  22 def find_command(lines):
  23     acc = []
  24     for num, line in enumerate(lines):
  25         # skip empty leading line
  26         if num == 0 and not line:
  27             continue
  28         cont = line.endswith('\\')
  29         if cont:
  30             line = line[:-1].rstrip()
  31         acc.append(line if not acc else line.lstrip())
  32         if not cont:
  33             break
  34     joined = ' '.join(acc)
  35     if not joined.startswith('$ '):
  36         raise NoCommand
  37     return joined[2:], lines[:num+1] + [''], lines[-1]
  38
  39 BORING_INTERFACES = [
  40     'org.freedesktop.DBus.Peer',
  41     'org.freedesktop.DBus.Introspectable',
  42     'org.freedesktop.DBus.Properties',
  43 ]
  44
  45 def print_method(declarations, elem, *, prefix, file, is_signal=False):
  46     name = elem.get('name')
  47     klass = 'signal' if is_signal else 'method'
  48     declarations[klass].append(name)
  49
  50     print(f'''{prefix}{name}(''', file=file, end='')
  51     lead = ',\n' + prefix + ' ' * len(name) + ' '
  52
  53     for num, arg in enumerate(elem.findall('./arg')):
  54         argname = arg.get('name')
  55
  56         if argname is None:
  57             if PRINT_ERRORS:
  58                 print(f'method {name}: argument {num+1} has no name', file=sys.stderr)
  59             argname = 'UNNAMED'
  60
  61         type = arg.get('type')
  62         if not is_signal:
  63             direction = arg.get('direction')
  64             print(f'''{lead if num > 0 else ''}{direction:3} {type} {argname}''', file=file, end='')
  65         else:
  66             print(f'''{lead if num > 0 else ''}{type} {argname}''', file=file, end='')
  67
  68     print(f');', file=file)
  69
  70 ACCESS_MAP = {
  71     'read' : 'readonly',
  72     'write' : 'readwrite',
  73 }
  74
  75 def value_ellipsis(type):
  76     if type == 's':
  77         return "'...'";
  78     if type[0] == 'a':
  79         inner = value_ellipsis(type[1:])
  80         return f"[{inner}{', ...' if inner != '...' else ''}]";
  81     return '...'
  82
  83 def print_property(declarations, elem, *, prefix, file):
  84     name = elem.get('name')
  85     type = elem.get('type')
  86     access = elem.get('access')
  87
  88     declarations['property'].append(name)
  89
  90     # @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
  91     # @org.freedesktop.systemd1.Privileged("true")
  92     # readwrite b EnableWallMessages = false;
  93
  94     for anno in elem.findall('./annotation'):
  95         anno_name = anno.get('name')
  96         anno_value = anno.get('value')
  97         print(f'''{prefix}@{anno_name}("{anno_value}")''', file=file)
  98
  99     access = ACCESS_MAP.get(access, access)
 100     print(f'''{prefix}{access} {type} {name} = {value_ellipsis(type)};''', file=file)
 101
 102 def print_interface(iface, *, prefix, file, print_boring, only_interface, declarations):
 103     name = iface.get('name')
 104
 105     is_boring = (name in BORING_INTERFACES or
 106                  only_interface is not None and name != only_interface)
 107
 108     if is_boring and print_boring:
 109         print(f'''{prefix}interface {name} {{ ... }};''', file=file)
 110
 111     elif not is_boring and not print_boring:
 112         print(f'''{prefix}interface {name} {{''', file=file)
 113         prefix2 = prefix + '  '
 114
 115         for num, elem in enumerate(iface.findall('./method')):
 116             if num == 0:
 117                 print(f'''{prefix2}methods:''', file=file)
 118             print_method(declarations, elem, prefix=prefix2 + '  ', file=file)
 119
 120         for num, elem in enumerate(iface.findall('./signal')):
 121             if num == 0:
 122                 print(f'''{prefix2}signals:''', file=file)
 123             print_method(declarations, elem, prefix=prefix2 + '  ', file=file, is_signal=True)
 124
 125         for num, elem in enumerate(iface.findall('./property')):
 126             if num == 0:
 127                 print(f'''{prefix2}properties:''', file=file)
 128             print_property(declarations, elem, prefix=prefix2 + '  ', file=file)
 129
 130         print(f'''{prefix}}};''', file=file)
 131
 132 def document_has_elem_with_text(document, elem, item_repr):
 133     predicate = f".//{elem}" # [text() = 'foo'] doesn't seem supported :(
 134     for loc in document.findall(predicate):
 135         if loc.text == item_repr:
 136             return True
 137     else:
 138         return False
 139
 140 def check_documented(document, declarations):
 141     missing = []
 142     for klass, items in declarations.items():
 143         for item in items:
 144             if klass == 'method':
 145                 elem = 'function'
 146                 item_repr = f'{item}()'
 147             elif klass == 'signal':
 148                 elem = 'function'
 149                 item_repr = item
 150             elif klass == 'property':
 151                 elem = 'varname'
 152                 item_repr = item
 153             else:
 154                 assert False, (klass, item)
 155
 156             if not document_has_elem_with_text(document, elem, item_repr):
 157                 if PRINT_ERRORS:
 158                     print(f'{klass} {item} is not documented :(')
 159                 missing.append((klass, item))
 160
 161     return missing
 162
 163 def xml_to_text(destination, xml, *, only_interface=None):
 164     file = io.StringIO()
 165
 166     declarations = collections.defaultdict(list)
 167
 168     print(f'''node {destination} {{''', file=file)
 169
 170     for print_boring in [False, True]:
 171         for iface in xml.findall('./interface'):
 172             print_interface(iface, prefix='  ', file=file,
 173                             print_boring=print_boring,
 174                             only_interface=only_interface,
 175                             declarations=declarations)
 176
 177     print(f'''}};''', file=file)
 178
 179     return file.getvalue(), declarations
 180
 181 def subst_output(document, programlisting):
 182     try:
 183         cmd, prefix_lines, footer = find_command(programlisting.text.splitlines())
 184     except NoCommand:
 185         return
 186
 187     only_interface = programlisting.get('interface', None)
 188
 189     argv = shlex.split(cmd)
 190     argv += ['--xml']
 191     print(f'COMMAND: {shlex.join(argv)}')
 192
 193     object_idx = argv.index('--object-path')
 194     object_path = argv[object_idx + 1]
 195
 196     try:
 197         out = subprocess.check_output(argv, text=True)
 198     except subprocess.CalledProcessError:
 199         print('command failed, ignoring', file=sys.stderr)
 200         return
 201
 202     xml = etree.fromstring(out, parser=PARSER)
 203
 204     new_text, declarations = xml_to_text(object_path, xml, only_interface=only_interface)
 205
 206     programlisting.text = '\n'.join(prefix_lines) + '\n' + new_text + footer
 207
 208     if declarations:
 209         missing = check_documented(document, declarations)
 210         parent = programlisting.getparent()
 211
 212         # delete old comments
 213         for child in parent:
 214             if (child.tag == etree.Comment
 215                 and 'not documented' in child.text):
 216                 parent.remove(child)
 217
 218         # insert comments for undocumented items
 219         for item in reversed(missing):
 220             comment = etree.Comment(f'{item[0]} {item[1]} is not documented!')
 221             comment.tail = programlisting.tail
 222             parent.insert(parent.index(programlisting) + 1, comment)
 223
 224 def process(page):
 225     src = open(page).read()
 226     xml = etree.fromstring(src, parser=PARSER)
 227
 228     # print('parsing {}'.format(name), file=sys.stderr)
 229     if xml.tag != 'refentry':
 230         return
 231
 232     pls = xml.findall('.//programlisting')
 233     for pl in pls:
 234         subst_output(xml, pl)
 235
 236     out_text = etree.tostring(xml, encoding='unicode')
 237     # massage format to avoid some lxml whitespace handling idiosyncracies
 238     # https://bugs.launchpad.net/lxml/+bug/526799
 239     out_text = (src[:src.find('<refentryinfo')] +
 240                 out_text[out_text.find('<refentryinfo'):] +
 241                 '\n')
 242
 243     with open(page, 'w') as out:
 244         out.write(out_text)
 245
 246 if __name__ == '__main__':
 247     pages = sys.argv[1:]
 248
 249     for page in pages:
 250         process(page)