3 # GDBus - GLib D-Bus Library
5 # Copyright (C) 2008-2011 Red Hat, Inc.
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.
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.
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.
22 # Author: David Zeuthen <davidz@redhat.com>
29 from . import dbustypes
32 # ----------------------------------------------------------------------------------------------------
34 class DocbookCodeGenerator
:
35 def __init__(self
, ifaces
, docbook
):
37 self
.docbook
= docbook
38 self
.generate_expand_dicts()
40 def print_method_prototype(self
, i
, m
, in_synopsis
):
44 max_method_len
= max(len(_m
.name
), max_method_len
)
46 max_method_len
= max(len(m
.name
), max_method_len
)
52 max_signature_len
= max(len(a
.signature
), max_signature_len
)
54 max_signature_len
= max(len(a
.signature
), max_signature_len
)
57 max_signature_len
= max(len(a
.signature
), max_signature_len
)
59 max_signature_len
= max(len(a
.signature
), max_signature_len
)
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
), ''))
65 self
.out
.write('%s%*s ('
66 %(m
.name
, max_method_len
- len(m
.name
), ''))
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
))
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
))
78 self
.out
.write(');\n')
80 def print_signal_prototype(self
, i
, s
, in_synopsis
):
84 max_signal_len
= max(len(_s
.name
), max_signal_len
)
86 max_signal_len
= max(len(s
.name
), max_signal_len
)
92 max_signature_len
= max(len(a
.signature
), max_signature_len
)
95 max_signature_len
= max(len(a
.signature
), max_signature_len
)
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
), ''))
101 self
.out
.write('%s%*s ('
102 %(s
.name
, max_signal_len
- len(s
.name
), ''))
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
))
109 self
.out
.write(');\n')
111 def print_property_prototype(self
, i
, p
, in_synopsis
):
114 for _p
in i
.properties
:
115 max_property_len
= max(len(_p
.name
), max_property_len
)
117 max_property_len
= max(len(p
.name
), max_property_len
)
119 max_signature_len
= 0
121 for _p
in i
.properties
:
122 max_signature_len
= max(len(_p
.signature
), max_signature_len
)
124 max_signature_len
= max(len(p
.signature
), max_signature_len
)
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
), ''))
130 self
.out
.write('%s%*s'
131 %(p
.name
, max_property_len
- len(p
.name
), ''))
132 if p
.readable
and p
.writable
:
138 self
.out
.write(' %s %s\n'%(access
, p
.signature
))
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'%())
146 self
.print_method_prototype(i
, m
, in_synopsis
=True)
147 self
.out
.write('</synopsis>\n'%())
148 self
.out
.write(' </refsynopsisdiv>\n'%())
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'%())
155 self
.print_signal_prototype(i
, s
, in_synopsis
=True)
156 self
.out
.write('</synopsis>\n'%())
157 self
.out
.write(' </refsect1>\n'%())
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'%())
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('<para>%s</para>\n'%(self
.expand(m
.doc_string
, True)))
176 self
.out
.write('<variablelist role="params">\n')
178 self
.out
.write('<varlistentry>\n'%())
179 self
.out
.write(' <term><literal>IN %s <parameter>%s</parameter></literal>:</term>\n'%(a
.signature
, a
.name
))
180 self
.out
.write(' <listitem><para>%s</para></listitem>\n'%(self
.expand(a
.doc_string
, True)))
181 self
.out
.write('</varlistentry>\n'%())
183 self
.out
.write('<varlistentry>\n'%())
184 self
.out
.write(' <term><literal>OUT %s <parameter>%s</parameter></literal>:</term>\n'%(a
.signature
, a
.name
))
185 self
.out
.write(' <listitem><para>%s</para></listitem>\n'%(self
.expand(a
.doc_string
, True)))
186 self
.out
.write('</varlistentry>\n'%())
187 self
.out
.write('</variablelist>\n')
189 self
.out
.write('<para role="since">Since %s</para>\n'%(m
.since
))
191 self
.out
.write('<warning><para>The %s() method is deprecated.</para></warning>'%(m
.name
))
192 self
.out
.write('</refsect2>\n')
194 def print_signal(self
, i
, s
):
195 self
.out
.write('<refsect2 role="signal" id="gdbus-signal-%s.%s">\n'%(utils
.dots_to_hyphens(i
.name
), s
.name
))
196 self
.out
.write(' <title>The "%s" signal</title>\n'%(s
.name
))
197 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
))
198 self
.out
.write('<programlisting>\n')
199 self
.print_signal_prototype(i
, s
, in_synopsis
=False)
200 self
.out
.write('</programlisting>\n')
201 self
.out
.write('<para>%s</para>\n'%(self
.expand(s
.doc_string
, True)))
202 self
.out
.write('<variablelist role="params">\n')
204 self
.out
.write('<varlistentry>\n'%())
205 self
.out
.write(' <term><literal>%s <parameter>%s</parameter></literal>:</term>\n'%(a
.signature
, a
.name
))
206 self
.out
.write(' <listitem><para>%s</para></listitem>\n'%(self
.expand(a
.doc_string
, True)))
207 self
.out
.write('</varlistentry>\n'%())
208 self
.out
.write('</variablelist>\n')
210 self
.out
.write('<para role="since">Since %s</para>\n'%(s
.since
))
212 self
.out
.write('<warning><para>The "%s" signal is deprecated.</para></warning>'%(s
.name
))
213 self
.out
.write('</refsect2>\n')
215 def print_property(self
, i
, p
):
216 self
.out
.write('<refsect2 role="property" id="gdbus-property-%s.%s">\n'%(utils
.dots_to_hyphens(i
.name
), p
.name
))
217 self
.out
.write(' <title>The "%s" property</title>\n'%(p
.name
))
218 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
))
219 self
.out
.write('<programlisting>\n')
220 self
.print_property_prototype(i
, p
, in_synopsis
=False)
221 self
.out
.write('</programlisting>\n')
222 self
.out
.write('<para>%s</para>\n'%(self
.expand(p
.doc_string
, True)))
224 self
.out
.write('<para role="since">Since %s</para>\n'%(p
.since
))
226 self
.out
.write('<warning><para>The "%s" property is deprecated.</para></warning>'%(p
.name
))
227 self
.out
.write('</refsect2>\n')
229 def expand(self
, s
, expandParamsAndConstants
):
230 for key
in self
.expand_member_dict_keys
:
231 s
= s
.replace(key
, self
.expand_member_dict
[key
])
232 for key
in self
.expand_iface_dict_keys
:
233 s
= s
.replace(key
, self
.expand_iface_dict
[key
])
234 if expandParamsAndConstants
:
235 # replace @foo with <parameter>foo</parameter>
236 s
= re
.sub('@[a-zA-Z0-9_]*', lambda m
: '<parameter>' + m
.group(0)[1:] + '</parameter>', s
)
237 # replace e.g. %TRUE with <constant>TRUE</constant>
238 s
= re
.sub('%[a-zA-Z0-9_]*', lambda m
: '<constant>' + m
.group(0)[1:] + '</constant>', s
)
241 def generate_expand_dicts(self
):
242 self
.expand_member_dict
= {}
243 self
.expand_iface_dict
= {}
244 for i
in self
.ifaces
:
246 value
= '<link linkend="gdbus-interface-%s.top_of_page">%s</link>'%(utils
.dots_to_hyphens(i
.name
), i
.name
)
247 self
.expand_iface_dict
[key
] = value
249 key
= '%s.%s()'%(i
.name
, m
.name
)
250 value
= '<link linkend="gdbus-method-%s.%s">%s()</link>'%(utils
.dots_to_hyphens(i
.name
), m
.name
, m
.name
)
251 self
.expand_member_dict
[key
] = value
253 key
= '#%s::%s'%(i
.name
, s
.name
)
254 value
= '<link linkend="gdbus-signal-%s.%s">"%s"</link>'%(utils
.dots_to_hyphens(i
.name
), s
.name
, s
.name
)
255 self
.expand_member_dict
[key
] = value
256 for p
in i
.properties
:
257 key
= '#%s:%s'%(i
.name
, p
.name
)
258 value
= '<link linkend="gdbus-property-%s.%s">"%s"</link>'%(utils
.dots_to_hyphens(i
.name
), p
.name
, p
.name
)
259 self
.expand_member_dict
[key
] = value
260 # Make sure to expand the keys in reverse order so e.g. #org.foo.Iface:MediaCompat
261 # is evaluated before #org.foo.Iface:Media ...
262 self
.expand_member_dict_keys
= sorted(self
.expand_member_dict
.keys(), reverse
=True)
263 self
.expand_iface_dict_keys
= sorted(self
.expand_iface_dict
.keys(), reverse
=True)
266 for i
in self
.ifaces
:
267 self
.out
= open('%s-%s.xml'%(self
.docbook
, i
.name
), 'w')
268 self
.out
.write(''%())
269 self
.out
.write('<?xml version="1.0" encoding="utf-8"?>\n'%())
270 self
.out
.write('<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"\n'%())
271 self
.out
.write(' "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [\n'%())
272 self
.out
.write(']>\n'%())
273 self
.out
.write('<refentry id="gdbus-%s">\n'%(i
.name
))
274 self
.out
.write(' <refmeta>'%())
275 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
))
276 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
))
277 self
.out
.write(' </refmeta>'%())
279 self
.out
.write(' <refnamediv>'%())
280 self
.out
.write(' <refname>%s</refname>'%(i
.name
))
281 self
.out
.write(' <refpurpose>%s</refpurpose>'%(i
.doc_string_brief
))
282 self
.out
.write(' </refnamediv>'%())
284 if len(i
.methods
) > 0:
285 self
.print_synopsis_methods(i
)
286 if len(i
.signals
) > 0:
287 self
.print_synopsis_signals(i
)
288 if len(i
.properties
) > 0:
289 self
.print_synopsis_properties(i
)
291 self
.out
.write('<refsect1 role="desc" id="gdbus-interface-%s">\n'%(utils
.dots_to_hyphens(i
.name
)))
292 self
.out
.write(' <title role="desc.title">Description</title>\n'%())
293 self
.out
.write(' <para>%s</para>\n'%(self
.expand(i
.doc_string
, True)))
295 self
.out
.write(' <para role="since">Since %s</para>\n'%(i
.since
))
297 self
.out
.write('<warning><para>The %s interface is deprecated.</para></warning>'%(i
.name
))
298 self
.out
.write('</refsect1>\n'%())
300 if len(i
.methods
) > 0:
301 self
.out
.write('<refsect1 role="details" id="gdbus-methods-%s">\n'%(i
.name
))
302 self
.out
.write(' <title role="details.title">Method Details</title>\n'%())
304 self
.print_method(i
, m
)
305 self
.out
.write('</refsect1>\n'%())
307 if len(i
.signals
) > 0:
308 self
.out
.write('<refsect1 role="details" id="gdbus-signals-%s">\n'%(i
.name
))
309 self
.out
.write(' <title role="details.title">Signal Details</title>\n'%())
311 self
.print_signal(i
, s
)
312 self
.out
.write('</refsect1>\n'%())
314 if len(i
.properties
) > 0:
315 self
.out
.write('<refsect1 role="details" id="gdbus-properties-%s">\n'%(i
.name
))
316 self
.out
.write(' <title role="details.title">Property Details</title>\n'%())
317 for s
in i
.properties
:
318 self
.print_property(i
, s
)
319 self
.out
.write('</refsect1>\n'%())
321 self
.out
.write('</refentry>\n')