gio/gdbus-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 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, write to the
  19 # Free Software Foundation, Inc., 59 Temple Place, Suite 330,
  20 # Boston, MA 02111-1307, USA.
  21 #
  22 # Author: David Zeuthen <davidz@redhat.com>
  23
  24 import sys
  25 import argparse
  26
  27 import config
  28 import utils
  29 import dbustypes
  30 import parser
  31
  32 # ----------------------------------------------------------------------------------------------------
  33
  34 class DocbookCodeGenerator:
  35     def __init__(self, ifaces, docbook):
  36         self.ifaces = ifaces
  37         self.docbook = docbook
  38
  39     def print_method_prototype(self, i, m, in_synopsis):
  40         max_method_len = 0
  41         if in_synopsis:
  42             for _m in i.methods:
  43                 max_method_len = max(len(_m.name), max_method_len)
  44         else:
  45             max_method_len = max(len(m.name), max_method_len)
  46
  47         max_signature_len = 0
  48         if in_synopsis:
  49             for _m in i.methods:
  50                 for a in _m.in_args:
  51                     max_signature_len = max(len(a.signature), max_signature_len)
  52                 for a in _m.out_args:
  53                     max_signature_len = max(len(a.signature), max_signature_len)
  54         else:
  55             for a in m.in_args:
  56                 max_signature_len = max(len(a.signature), max_signature_len)
  57             for a in m.out_args:
  58                 max_signature_len = max(len(a.signature), max_signature_len)
  59
  60         if in_synopsis:
  61             self.out.write('<link linkend="gdbus-method-%s.%s">%s</link>%*s ('
  62                            %(utils.dots_to_hyphens(i.name), m.name, m.name, max_method_len - len(m.name), ''))
  63         else:
  64             self.out.write('%s%*s ('
  65                            %(m.name, max_method_len - len(m.name), ''))
  66         count = 0
  67         for a in m.in_args:
  68             if (count > 0):
  69                 self.out.write(',\n%*s'%(max_method_len + 2, ''))
  70             self.out.write('IN  %s%*s %s'%(a.signature, max_signature_len - len(a.signature), '', a.name))
  71             count = count + 1
  72         for a in m.out_args:
  73             if (count > 0):
  74                 self.out.write(',\n%*s'%(max_method_len + 2, ''))
  75             self.out.write('OUT %s%*s %s'%(a.signature, max_signature_len - len(a.signature), '', a.name))
  76             count = count + 1
  77         self.out.write(');\n')
  78
  79     def print_signal_prototype(self, i, s, in_synopsis):
  80         max_signal_len = 0
  81         if in_synopsis:
  82             for _s in i.signals:
  83                 max_signal_len = max(len(_s.name), max_signal_len)
  84         else:
  85             max_signal_len = max(len(s.name), max_signal_len)
  86
  87         max_signature_len = 0
  88         if in_synopsis:
  89             for _s in i.signals:
  90                 for a in _s.args:
  91                     max_signature_len = max(len(a.signature), max_signature_len)
  92         else:
  93             for a in s.args:
  94                 max_signature_len = max(len(a.signature), max_signature_len)
  95
  96         if in_synopsis:
  97             self.out.write('<link linkend="gdbus-signal-%s.%s">%s</link>%*s ('
  98                            %(utils.dots_to_hyphens(i.name), s.name, s.name, max_signal_len - len(s.name), ''))
  99         else:
 100             self.out.write('%s%*s ('
 101                            %(s.name, max_signal_len - len(s.name), ''))
 102         count = 0
 103         for a in s.args:
 104             if (count > 0):
 105                 self.out.write(',\n%*s'%(max_signal_len + 2, ''))
 106             self.out.write('%s%*s %s'%(a.signature, max_signature_len - len(a.signature), '', a.name))
 107             count = count + 1
 108         self.out.write(');\n')
 109
 110     def print_property_prototype(self, i, p, in_synopsis):
 111         max_property_len = 0
 112         if in_synopsis:
 113             for _p in i.properties:
 114                 max_property_len = max(len(_p.name), max_property_len)
 115         else:
 116             max_property_len = max(len(p.name), max_property_len)
 117
 118         max_signature_len = 0
 119         if in_synopsis:
 120             for _p in i.properties:
 121                 max_signature_len = max(len(_p.signature), max_signature_len)
 122         else:
 123             max_signature_len = max(len(p.signature), max_signature_len)
 124
 125         if in_synopsis:
 126             self.out.write('<link linkend="gdbus-property-%s.%s">%s</link>%*s'
 127                            %(utils.dots_to_hyphens(i.name), p.name, p.name, max_property_len - len(p.name), ''))
 128         else:
 129             self.out.write('%s%*s'
 130                            %(p.name, max_property_len - len(p.name), ''))
 131         if p.readable and p.writable:
 132             access = 'readwrite'
 133         elif p.readable:
 134             access = 'readable '
 135         else:
 136             access = 'writable '
 137         self.out.write('  %s  %s\n'%(access, p.signature))
 138
 139
 140     def print_synopsis_methods(self, i):
 141         self.out.write('  <refsynopsisdiv role="synopsis">\n'%())
 142         self.out.write('    <title role="synopsis.title">Methods</title>\n'%())
 143         self.out.write('    <synopsis>\n'%())
 144         for m in i.methods:
 145             self.print_method_prototype(i, m, in_synopsis=True)
 146         self.out.write('</synopsis>\n'%())
 147         self.out.write('  </refsynopsisdiv>\n'%())
 148
 149     def print_synopsis_signals(self, i):
 150         self.out.write('  <refsect1 role="signal_proto">\n'%())
 151         self.out.write('    <title role="signal_proto.title">Signals</title>\n'%())
 152         self.out.write('    <synopsis>\n'%())
 153         for s in i.signals:
 154             self.print_signal_prototype(i, s, in_synopsis=True)
 155         self.out.write('</synopsis>\n'%())
 156         self.out.write('  </refsect1>\n'%())
 157
 158     def print_synopsis_properties(self, i):
 159         self.out.write('  <refsect1 role="properties">\n'%())
 160         self.out.write('    <title role="properties.title">Properties</title>\n'%())
 161         self.out.write('    <synopsis>\n'%())
 162         for p in i.properties:
 163             self.print_property_prototype(i, p, in_synopsis=True)
 164         self.out.write('</synopsis>\n'%())
 165         self.out.write('  </refsect1>\n'%())
 166
 167     def print_method(self, i, m):
 168         self.out.write('<refsect2 role="method" id="gdbus-method-%s.%s">\n'%(utils.dots_to_hyphens(i.name), m.name))
 169         self.out.write('  <title>The %s() method</title>\n'%(m.name))
 170         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))
 171         self.out.write('<programlisting>\n')
 172         self.print_method_prototype(i, m, in_synopsis=False)
 173         self.out.write('</programlisting>\n')
 174         self.out.write('<para>%s</para>\n'%(self.expand(m.doc_string)))
 175         self.out.write('<variablelist role="params">\n')
 176         for a in m.in_args:
 177             self.out.write('<varlistentry>\n'%())
 178             self.out.write('  <term><literal>IN %s <parameter>%s</parameter></literal>:</term>\n'%(a.signature, a.name))
 179             self.out.write('  <listitem><para>%s</para></listitem>\n'%(self.expand(a.doc_string)))
 180             self.out.write('</varlistentry>\n'%())
 181         for a in m.out_args:
 182             self.out.write('<varlistentry>\n'%())
 183             self.out.write('  <term><literal>OUT %s <parameter>%s</parameter></literal>:</term>\n'%(a.signature, a.name))
 184             self.out.write('  <listitem><para>%s</para></listitem>\n'%(self.expand(a.doc_string)))
 185             self.out.write('</varlistentry>\n'%())
 186         self.out.write('</variablelist>\n')
 187         if len(m.since) > 0:
 188             self.out.write('<para role="since">Since %s</para>\n'%(m.since))
 189         if m.deprecated:
 190             self.out.write('<warning><para>The %s() method is deprecated.</para></warning>'%(m.name))
 191         self.out.write('</refsect2>\n')
 192
 193     def print_signal(self, i, s):
 194         self.out.write('<refsect2 role="signal" id="gdbus-signal-%s.%s">\n'%(utils.dots_to_hyphens(i.name), s.name))
 195         self.out.write('  <title>The "%s" signal</title>\n'%(s.name))
 196         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))
 197         self.out.write('<programlisting>\n')
 198         self.print_signal_prototype(i, s, in_synopsis=False)
 199         self.out.write('</programlisting>\n')
 200         self.out.write('<para>%s</para>\n'%(self.expand(s.doc_string)))
 201         self.out.write('<variablelist role="params">\n')
 202         for a in s.args:
 203             self.out.write('<varlistentry>\n'%())
 204             self.out.write('  <term><literal>%s <parameter>%s</parameter></literal>:</term>\n'%(a.signature, a.name))
 205             self.out.write('  <listitem><para>%s</para></listitem>\n'%(self.expand(a.doc_string)))
 206             self.out.write('</varlistentry>\n'%())
 207         self.out.write('</variablelist>\n')
 208         if len(s.since) > 0:
 209             self.out.write('<para role="since">Since %s</para>\n'%(s.since))
 210         if s.deprecated:
 211             self.out.write('<warning><para>The "%s" signal is deprecated.</para></warning>'%(s.name))
 212         self.out.write('</refsect2>\n')
 213
 214     def print_property(self, i, p):
 215         self.out.write('<refsect2 role="property" id="gdbus-property-%s.%s">\n'%(utils.dots_to_hyphens(i.name), p.name))
 216         self.out.write('  <title>The "%s" property</title>\n'%(p.name))
 217         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))
 218         self.out.write('<programlisting>\n')
 219         self.print_property_prototype(i, p, in_synopsis=False)
 220         self.out.write('</programlisting>\n')
 221         self.out.write('<para>%s</para>\n'%(self.expand(p.doc_string)))
 222         if len(p.since) > 0:
 223             self.out.write('<para role="since">Since %s</para>\n'%(p.since))
 224         if p.deprecated:
 225             self.out.write('<warning><para>The "%s" property is deprecated.</para></warning>'%(p.name))
 226         self.out.write('</refsect2>\n')
 227
 228     def expand(self, s):
 229         for key in self.expand_member_dict_keys:
 230             s = s.replace(key, self.expand_member_dict[key])
 231         for key in self.expand_iface_dict_keys:
 232             s = s.replace(key, self.expand_iface_dict[key])
 233         return s
 234
 235     def generate_expand_dicts(self):
 236         self.expand_member_dict = {}
 237         self.expand_iface_dict = {}
 238         for i in self.ifaces:
 239             key = '#%s'%(i.name)
 240             value = '<link linkend="gdbus-interface-%s.top_of_page">%s</link>'%(utils.dots_to_hyphens(i.name), i.name)
 241             self.expand_iface_dict[key] = value
 242             for m in i.methods:
 243                 key = '%s.%s()'%(i.name, m.name)
 244                 value = '<link linkend="gdbus-method-%s.%s">%s()</link>'%(utils.dots_to_hyphens(i.name), m.name, m.name)
 245                 self.expand_member_dict[key] = value
 246             for s in i.signals:
 247                 key = '#%s::%s'%(i.name, s.name)
 248                 value = '<link linkend="gdbus-signal-%s.%s">"%s"</link>'%(utils.dots_to_hyphens(i.name), s.name, s.name)
 249                 self.expand_member_dict[key] = value
 250             for p in i.properties:
 251                 key = '#%s:%s'%(i.name, p.name)
 252                 value = '<link linkend="gdbus-property-%s.%s">"%s"</link>'%(utils.dots_to_hyphens(i.name), p.name, p.name)
 253                 self.expand_member_dict[key] = value
 254         # Make sure to expand the keys in reverse order so e.g. #org.foo.Iface:MediaCompat
 255         # is evaluated before #org.foo.Iface:Media ...
 256         self.expand_member_dict_keys = self.expand_member_dict.keys()
 257         self.expand_member_dict_keys.sort(reverse=True)
 258         self.expand_iface_dict_keys = self.expand_iface_dict.keys()
 259         self.expand_iface_dict_keys.sort(reverse=True)
 260
 261     def generate(self):
 262         self.generate_expand_dicts()
 263         for i in self.ifaces:
 264             self.out = file('%s-%s.xml'%(self.docbook, i.name), 'w')
 265             self.out.write(''%())
 266             self.out.write('<?xml version="1.0" encoding="utf-8"?>\n'%())
 267             self.out.write('<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"\n'%())
 268             self.out.write('               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [\n'%())
 269             self.out.write(']>\n'%())
 270             self.out.write('<refentry id="gdbus-%s">\n'%(i.name))
 271             self.out.write('  <refmeta>'%())
 272             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))
 273             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))
 274             self.out.write('  </refmeta>'%())
 275
 276             self.out.write('  <refnamediv>'%())
 277             self.out.write('    <refname>%s</refname>'%(i.name))
 278             self.out.write('    <refpurpose>%s</refpurpose>'%(i.doc_string_brief))
 279             self.out.write('  </refnamediv>'%())
 280
 281             if len(i.methods) > 0:
 282                 self.print_synopsis_methods(i)
 283             if len(i.signals) > 0:
 284                 self.print_synopsis_signals(i)
 285             if len(i.properties) > 0:
 286                 self.print_synopsis_properties(i)
 287
 288             self.out.write('<refsect1 role="desc" id="gdbus-interface-%s">\n'%(utils.dots_to_hyphens(i.name)))
 289             self.out.write('  <title role="desc.title">Description</title>\n'%())
 290             self.out.write('  <para>%s</para>\n'%(self.expand(i.doc_string)))
 291             if len(i.since) > 0:
 292                 self.out.write('  <para role="since">Since %s</para>\n'%(i.since))
 293             if i.deprecated:
 294                 self.out.write('<warning><para>The %s interface is deprecated.</para></warning>'%(i.name))
 295             self.out.write('</refsect1>\n'%())
 296
 297             if len(i.methods) > 0:
 298                 self.out.write('<refsect1 role="details" id="gdbus-methods-%s">\n'%(i.name))
 299                 self.out.write('  <title role="details.title">Method Details</title>\n'%())
 300                 for m in i.methods:
 301                     self.print_method(i, m)
 302                 self.out.write('</refsect1>\n'%())
 303
 304             if len(i.signals) > 0:
 305                 self.out.write('<refsect1 role="details" id="gdbus-signals-%s">\n'%(i.name))
 306                 self.out.write('  <title role="details.title">Signal Details</title>\n'%())
 307                 for s in i.signals:
 308                     self.print_signal(i, s)
 309                 self.out.write('</refsect1>\n'%())
 310
 311             if len(i.properties) > 0:
 312                 self.out.write('<refsect1 role="details" id="gdbus-properties-%s">\n'%(i.name))
 313                 self.out.write('  <title role="details.title">Property Details</title>\n'%())
 314                 for s in i.properties:
 315                     self.print_property(i, s)
 316                 self.out.write('</refsect1>\n'%())
 317
 318             self.out.write('</refentry>\n')
 319             self.out.write('\n')
 320