gio/gdbus-2.0/codegen/codegen_docbook.py

   1 # -*- Mode: Python -*-
   2
   3 # GDBus - GLib D-Bus Library
   4 #
   5 # Copyright (C) 2008-2011 Red Hat, Inc.
   6 #
   7 # This library is free software; you can redistribute it and/or
   8 # modify it under the terms of the GNU Lesser General Public
   9 # License as published by the Free Software Foundation; either
  10 # version 2.1 of the License, or (at your option) any later version.
  11 #
  12 # This library is distributed in the hope that it will be useful,
  13 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15 # Lesser General Public License for more details.
  16 #
  17 # You should have received a copy of the GNU Lesser General
  18 # Public License along with this library; if not, see <http://www.gnu.org/licenses/>.
  19 #
  20 # Author: David Zeuthen <davidz@redhat.com>
  21
  22 import sys
  23 import re
  24 from os import path
  25
  26 from . import config
  27 from . import utils
  28 from . import dbustypes
  29 from . import parser
  30
  31 # ----------------------------------------------------------------------------------------------------
  32
  33 class DocbookCodeGenerator:
  34     def __init__(self, ifaces, docbook, outdir):
  35         self.ifaces = ifaces
  36         self.docbook = docbook
  37         self.outdir = outdir
  38         self.generate_expand_dicts()
  39
  40     def print_method_prototype(self, i, m, in_synopsis):
  41         max_method_len = 0
  42         if in_synopsis:
  43             for _m in i.methods:
  44                 max_method_len = max(len(_m.name), max_method_len)
  45         else:
  46             max_method_len = max(len(m.name), max_method_len)
  47
  48         max_signature_len = 0
  49         if in_synopsis:
  50             for _m in i.methods:
  51                 for a in _m.in_args:
  52                     max_signature_len = max(len(a.signature), max_signature_len)
  53                 for a in _m.out_args:
  54                     max_signature_len = max(len(a.signature), max_signature_len)
  55         else:
  56             for a in m.in_args:
  57                 max_signature_len = max(len(a.signature), max_signature_len)
  58             for a in m.out_args:
  59                 max_signature_len = max(len(a.signature), max_signature_len)
  60
  61         if in_synopsis:
  62             self.out.write('<link linkend="gdbus-method-%s.%s">%s</link>%*s ('
  63                            %(utils.dots_to_hyphens(i.name), m.name, m.name, max_method_len - len(m.name), ''))
  64         else:
  65             self.out.write('%s%*s ('
  66                            %(m.name, max_method_len - len(m.name), ''))
  67         count = 0
  68         for a in m.in_args:
  69             if (count > 0):
  70                 self.out.write(',\n%*s'%(max_method_len + 2, ''))
  71             self.out.write('IN  %s%*s %s'%(a.signature, max_signature_len - len(a.signature), '', a.name))
  72             count = count + 1
  73         for a in m.out_args:
  74             if (count > 0):
  75                 self.out.write(',\n%*s'%(max_method_len + 2, ''))
  76             self.out.write('OUT %s%*s %s'%(a.signature, max_signature_len - len(a.signature), '', a.name))
  77             count = count + 1
  78         self.out.write(');\n')
  79
  80     def print_signal_prototype(self, i, s, in_synopsis):
  81         max_signal_len = 0
  82         if in_synopsis:
  83             for _s in i.signals:
  84                 max_signal_len = max(len(_s.name), max_signal_len)
  85         else:
  86             max_signal_len = max(len(s.name), max_signal_len)
  87
  88         max_signature_len = 0
  89         if in_synopsis:
  90             for _s in i.signals:
  91                 for a in _s.args:
  92                     max_signature_len = max(len(a.signature), max_signature_len)
  93         else:
  94             for a in s.args:
  95                 max_signature_len = max(len(a.signature), max_signature_len)
  96
  97         if in_synopsis:
  98             self.out.write('<link linkend="gdbus-signal-%s.%s">%s</link>%*s ('
  99                            %(utils.dots_to_hyphens(i.name), s.name, s.name, max_signal_len - len(s.name), ''))
 100         else:
 101             self.out.write('%s%*s ('
 102                            %(s.name, max_signal_len - len(s.name), ''))
 103         count = 0
 104         for a in s.args:
 105             if (count > 0):
 106                 self.out.write(',\n%*s'%(max_signal_len + 2, ''))
 107             self.out.write('%s%*s %s'%(a.signature, max_signature_len - len(a.signature), '', a.name))
 108             count = count + 1
 109         self.out.write(');\n')
 110
 111     def print_property_prototype(self, i, p, in_synopsis):
 112         max_property_len = 0
 113         if in_synopsis:
 114             for _p in i.properties:
 115                 max_property_len = max(len(_p.name), max_property_len)
 116         else:
 117             max_property_len = max(len(p.name), max_property_len)
 118
 119         max_signature_len = 0
 120         if in_synopsis:
 121             for _p in i.properties:
 122                 max_signature_len = max(len(_p.signature), max_signature_len)
 123         else:
 124             max_signature_len = max(len(p.signature), max_signature_len)
 125
 126         if in_synopsis:
 127             self.out.write('<link linkend="gdbus-property-%s.%s">%s</link>%*s'
 128                            %(utils.dots_to_hyphens(i.name), p.name, p.name, max_property_len - len(p.name), ''))
 129         else:
 130             self.out.write('%s%*s'
 131                            %(p.name, max_property_len - len(p.name), ''))
 132         if p.readable and p.writable:
 133             access = 'readwrite'
 134         elif p.readable:
 135             access = 'readable '
 136         else:
 137             access = 'writable '
 138         self.out.write('  %s  %s\n'%(access, p.signature))
 139
 140
 141     def print_synopsis_methods(self, i):
 142         self.out.write('  <refsynopsisdiv role="synopsis">\n'%())
 143         self.out.write('    <title role="synopsis.title">Methods</title>\n'%())
 144         self.out.write('    <synopsis>\n'%())
 145         for m in i.methods:
 146             self.print_method_prototype(i, m, in_synopsis=True)
 147         self.out.write('</synopsis>\n'%())
 148         self.out.write('  </refsynopsisdiv>\n'%())
 149
 150     def print_synopsis_signals(self, i):
 151         self.out.write('  <refsect1 role="signal_proto">\n'%())
 152         self.out.write('    <title role="signal_proto.title">Signals</title>\n'%())
 153         self.out.write('    <synopsis>\n'%())
 154         for s in i.signals:
 155             self.print_signal_prototype(i, s, in_synopsis=True)
 156         self.out.write('</synopsis>\n'%())
 157         self.out.write('  </refsect1>\n'%())
 158
 159     def print_synopsis_properties(self, i):
 160         self.out.write('  <refsect1 role="properties">\n'%())
 161         self.out.write('    <title role="properties.title">Properties</title>\n'%())
 162         self.out.write('    <synopsis>\n'%())
 163         for p in i.properties:
 164             self.print_property_prototype(i, p, in_synopsis=True)
 165         self.out.write('</synopsis>\n'%())
 166         self.out.write('  </refsect1>\n'%())
 167
 168     def print_method(self, i, m):
 169         self.out.write('<refsect2 role="method" id="gdbus-method-%s.%s">\n'%(utils.dots_to_hyphens(i.name), m.name))
 170         self.out.write('  <title>The %s() method</title>\n'%(m.name))
 171         self.out.write('  <indexterm zone="gdbus-method-%s.%s"><primary sortas="%s.%s">%s.%s()</primary></indexterm>\n'%(utils.dots_to_hyphens(i.name), m.name, i.name_without_prefix, m.name, i.name, m.name))
 172         self.out.write('<programlisting>\n')
 173         self.print_method_prototype(i, m, in_synopsis=False)
 174         self.out.write('</programlisting>\n')
 175         self.out.write('%s\n'%(self.expand_paras(m.doc_string, True)))
 176         if m.in_args or m.out_args:
 177             self.out.write('<variablelist role="params">\n')
 178             for a in m.in_args:
 179                 self.out.write('<varlistentry>\n'%())
 180                 self.out.write('  <term><literal>IN %s <parameter>%s</parameter></literal>:</term>\n'%(a.signature, a.name))
 181                 self.out.write('  <listitem>%s</listitem>\n'%(self.expand_paras(a.doc_string, True)))
 182                 self.out.write('</varlistentry>\n'%())
 183             for a in m.out_args:
 184                 self.out.write('<varlistentry>\n'%())
 185                 self.out.write('  <term><literal>OUT %s <parameter>%s</parameter></literal>:</term>\n'%(a.signature, a.name))
 186                 self.out.write('  <listitem>%s</listitem>\n'%(self.expand_paras(a.doc_string, True)))
 187                 self.out.write('</varlistentry>\n'%())
 188             self.out.write('</variablelist>\n')
 189         if len(m.since) > 0:
 190             self.out.write('<para role="since">Since %s</para>\n'%(m.since))
 191         if m.deprecated:
 192             self.out.write('<warning><para>The %s() method is deprecated.</para></warning>'%(m.name))
 193         self.out.write('</refsect2>\n')
 194
 195     def print_signal(self, i, s):
 196         self.out.write('<refsect2 role="signal" id="gdbus-signal-%s.%s">\n'%(utils.dots_to_hyphens(i.name), s.name))
 197         self.out.write('  <title>The "%s" signal</title>\n'%(s.name))
 198         self.out.write('  <indexterm zone="gdbus-signal-%s.%s"><primary sortas="%s::%s">%s::%s</primary></indexterm>\n'%(utils.dots_to_hyphens(i.name), s.name, i.name_without_prefix, s.name, i.name, s.name))
 199         self.out.write('<programlisting>\n')
 200         self.print_signal_prototype(i, s, in_synopsis=False)
 201         self.out.write('</programlisting>\n')
 202         self.out.write('%s\n'%(self.expand_paras(s.doc_string, True)))
 203         if s.args:
 204             self.out.write('<variablelist role="params">\n')
 205             for a in s.args:
 206                 self.out.write('<varlistentry>\n'%())
 207                 self.out.write('  <term><literal>%s <parameter>%s</parameter></literal>:</term>\n'%(a.signature, a.name))
 208                 self.out.write('  <listitem>%s</listitem>\n'%(self.expand_paras(a.doc_string, True)))
 209                 self.out.write('</varlistentry>\n'%())
 210             self.out.write('</variablelist>\n')
 211         if len(s.since) > 0:
 212             self.out.write('<para role="since">Since %s</para>\n'%(s.since))
 213         if s.deprecated:
 214             self.out.write('<warning><para>The "%s" signal is deprecated.</para></warning>'%(s.name))
 215         self.out.write('</refsect2>\n')
 216
 217     def print_property(self, i, p):
 218         self.out.write('<refsect2 role="property" id="gdbus-property-%s.%s">\n'%(utils.dots_to_hyphens(i.name), p.name))
 219         self.out.write('  <title>The "%s" property</title>\n'%(p.name))
 220         self.out.write('  <indexterm zone="gdbus-property-%s.%s"><primary sortas="%s:%s">%s:%s</primary></indexterm>\n'%(utils.dots_to_hyphens(i.name), p.name, i.name_without_prefix, p.name, i.name, p.name))
 221         self.out.write('<programlisting>\n')
 222         self.print_property_prototype(i, p, in_synopsis=False)
 223         self.out.write('</programlisting>\n')
 224         self.out.write('%s\n'%(self.expand_paras(p.doc_string, True)))
 225         if len(p.since) > 0:
 226             self.out.write('<para role="since">Since %s</para>\n'%(p.since))
 227         if p.deprecated:
 228             self.out.write('<warning><para>The "%s" property is deprecated.</para></warning>'%(p.name))
 229         self.out.write('</refsect2>\n')
 230
 231     def expand(self, s, expandParamsAndConstants):
 232         for key in self.expand_member_dict_keys:
 233             s = s.replace(key, self.expand_member_dict[key])
 234         for key in self.expand_iface_dict_keys:
 235             s = s.replace(key, self.expand_iface_dict[key])
 236         if expandParamsAndConstants:
 237             # replace @foo with <parameter>foo</parameter>
 238             s = re.sub('@[a-zA-Z0-9_]*', lambda m: '<parameter>' + m.group(0)[1:] + '</parameter>', s)
 239             # replace e.g. %TRUE with <constant>TRUE</constant>
 240             s = re.sub('%[a-zA-Z0-9_]*', lambda m: '<constant>' + m.group(0)[1:] + '</constant>', s)
 241         return s
 242
 243     def expand_paras(self, s, expandParamsAndConstants):
 244         s = self.expand(s, expandParamsAndConstants).strip()
 245         if not s.startswith("<para"):
 246             s = "<para>%s</para>" % s
 247         return s
 248
 249     def generate_expand_dicts(self):
 250         self.expand_member_dict = {}
 251         self.expand_iface_dict = {}
 252         for i in self.ifaces:
 253             key = '#%s'%(i.name)
 254             value = '<link linkend="gdbus-interface-%s.top_of_page">%s</link>'%(utils.dots_to_hyphens(i.name), i.name)
 255             self.expand_iface_dict[key] = value
 256             for m in i.methods:
 257                 key = '%s.%s()'%(i.name, m.name)
 258                 value = '<link linkend="gdbus-method-%s.%s">%s()</link>'%(utils.dots_to_hyphens(i.name), m.name, m.name)
 259                 self.expand_member_dict[key] = value
 260             for s in i.signals:
 261                 key = '#%s::%s'%(i.name, s.name)
 262                 value = '<link linkend="gdbus-signal-%s.%s">"%s"</link>'%(utils.dots_to_hyphens(i.name), s.name, s.name)
 263                 self.expand_member_dict[key] = value
 264             for p in i.properties:
 265                 key = '#%s:%s'%(i.name, p.name)
 266                 value = '<link linkend="gdbus-property-%s.%s">"%s"</link>'%(utils.dots_to_hyphens(i.name), p.name, p.name)
 267                 self.expand_member_dict[key] = value
 268         # Make sure to expand the keys in reverse order so e.g. #org.foo.Iface:MediaCompat
 269         # is evaluated before #org.foo.Iface:Media ...
 270         self.expand_member_dict_keys = sorted(self.expand_member_dict.keys(), reverse=True)
 271         self.expand_iface_dict_keys = sorted(self.expand_iface_dict.keys(), reverse=True)
 272
 273     def generate(self):
 274         for i in self.ifaces:
 275             self.out = open(path.join(self.outdir, '%s-%s.xml'%(self.docbook, i.name)), 'w')
 276             self.out.write(''%())
 277             self.out.write('<?xml version="1.0" encoding="utf-8"?>\n'%())
 278             self.out.write('<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"\n'%())
 279             self.out.write('               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [\n'%())
 280             self.out.write(']>\n'%())
 281             self.out.write('<refentry id="gdbus-%s">\n'%(i.name))
 282             self.out.write('  <refmeta>'%())
 283             self.out.write('    <refentrytitle role="top_of_page" id="gdbus-interface-%s.top_of_page">%s</refentrytitle>\n'%(utils.dots_to_hyphens(i.name), i.name))
 284             self.out.write('  <indexterm zone="gdbus-interface-%s.top_of_page"><primary sortas="%s">%s</primary></indexterm>\n'%(utils.dots_to_hyphens(i.name), i.name_without_prefix, i.name))
 285             self.out.write('  </refmeta>'%())
 286
 287             self.out.write('  <refnamediv>'%())
 288             self.out.write('    <refname>%s</refname>'%(i.name))
 289             self.out.write('    <refpurpose>%s</refpurpose>'%(i.doc_string_brief))
 290             self.out.write('  </refnamediv>'%())
 291
 292             if len(i.methods) > 0:
 293                 self.print_synopsis_methods(i)
 294             if len(i.signals) > 0:
 295                 self.print_synopsis_signals(i)
 296             if len(i.properties) > 0:
 297                 self.print_synopsis_properties(i)
 298
 299             self.out.write('<refsect1 role="desc" id="gdbus-interface-%s">\n'%(utils.dots_to_hyphens(i.name)))
 300             self.out.write('  <title role="desc.title">Description</title>\n'%())
 301             self.out.write('  %s\n'%(self.expand_paras(i.doc_string, True)))
 302             if len(i.since) > 0:
 303                 self.out.write('  <para role="since">Since %s</para>\n'%(i.since))
 304             if i.deprecated:
 305                 self.out.write('<warning><para>The %s interface is deprecated.</para></warning>'%(i.name))
 306             self.out.write('</refsect1>\n'%())
 307
 308             if len(i.methods) > 0:
 309                 self.out.write('<refsect1 role="details" id="gdbus-methods-%s">\n'%(i.name))
 310                 self.out.write('  <title role="details.title">Method Details</title>\n'%())
 311                 for m in i.methods:
 312                     self.print_method(i, m)
 313                 self.out.write('</refsect1>\n'%())
 314
 315             if len(i.signals) > 0:
 316                 self.out.write('<refsect1 role="details" id="gdbus-signals-%s">\n'%(i.name))
 317                 self.out.write('  <title role="details.title">Signal Details</title>\n'%())
 318                 for s in i.signals:
 319                     self.print_signal(i, s)
 320                 self.out.write('</refsect1>\n'%())
 321
 322             if len(i.properties) > 0:
 323                 self.out.write('<refsect1 role="details" id="gdbus-properties-%s">\n'%(i.name))
 324                 self.out.write('  <title role="details.title">Property Details</title>\n'%())
 325                 for s in i.properties:
 326                     self.print_property(i, s)
 327                 self.out.write('</refsect1>\n'%())
 328
 329             self.out.write('</refentry>\n')
 330             self.out.write('\n')
 331