3 # This work is licensed under the terms of the GNU LGPL, version 2+.
4 # See the COPYING file in the top-level directory.
5 """This script produces the documentation of a qapi schema in texinfo format"""
7 from __future__
import print_function
9 from qapi
.gen
import QAPIGenDoc
, QAPISchemaVisitor
13 @deftypefn {type} {{}} {name}
15 {body}{members}{features}{sections}
21 @deftp {{{type}}} {name}
23 {body}{members}{features}{sections}
28 EXAMPLE_FMT
= """@example
34 def subst_strong(doc
):
35 """Replaces *foo* by @strong{foo}"""
36 return re
.sub(r
'\*([^*\n]+)\*', r
'@strong{\1}', doc
)
40 """Replaces _foo_ by @emph{foo}"""
41 return re
.sub(r
'\b_([^_\n]+)_\b', r
'@emph{\1}', doc
)
45 """Replaces @var by @code{var}"""
46 return re
.sub(r
'@([\w-]+)', r
'@code{\1}', doc
)
49 def subst_braces(doc
):
50 """Replaces {} with @{ @}"""
51 return doc
.replace('{', '@{').replace('}', '@}')
54 def texi_example(doc
):
56 # TODO: Neglects to escape @ characters.
57 # We should probably escape them in subst_braces(), and rename the
58 # function to subst_special() or subs_texi_special(). If we do that, we
59 # need to delay it until after subst_vars() in texi_format().
60 doc
= subst_braces(doc
).strip('\n')
61 return EXAMPLE_FMT(code
=doc
)
69 - |: generates an @example
70 - =: generates @section
71 - ==: generates @subsection
72 - 1. or 1): generates an @enumerate @item
73 - */-: generates an @itemize list
76 doc
= subst_braces(doc
)
79 doc
= subst_strong(doc
)
82 for line
in doc
.split('\n'):
85 # FIXME: Doing this in a single if / elif chain is
86 # problematic. For instance, a line without markup terminates
87 # a list if it follows a blank line (reaches the final elif),
88 # but a line with some *other* markup, such as a = title
91 # Make sure to update section "Documentation markup" in
92 # docs/devel/qapi-code-gen.txt when fixing this.
93 if line
.startswith('| '):
94 line
= EXAMPLE_FMT(code
=line
[2:])
95 elif line
.startswith('= '):
96 line
= '@section ' + line
[2:]
97 elif line
.startswith('== '):
98 line
= '@subsection ' + line
[3:]
99 elif re
.match(r
'^([0-9]*\.) ', line
):
101 ret
+= '@enumerate\n'
104 line
= line
[line
.find(' ')+1:]
105 elif re
.match(r
'^[*-] ', line
):
107 ret
+= '@itemize %s\n' % {'*': '@bullet',
108 '-': '@minus'}[line
[0]]
112 elif lastempty
and inlist
:
113 ret
+= '@end %s\n\n' % inlist
120 ret
+= '@end %s\n\n' % inlist
125 """Format the main documentation body"""
126 return texi_format(doc
.body
.text
)
129 def texi_if(ifcond
, prefix
='\n', suffix
='\n'):
130 """Format the #if condition"""
133 return '%s@b{If:} @code{%s}%s' % (prefix
, ', '.join(ifcond
), suffix
)
136 def texi_enum_value(value
, desc
, suffix
):
137 """Format a table of members item for an enumeration value"""
138 return '@item @code{%s}\n%s%s' % (
139 value
.name
, desc
, texi_if(value
.ifcond
, prefix
='@*'))
142 def texi_member(member
, desc
, suffix
):
143 """Format a table of members item for an object type member"""
144 typ
= member
.type.doc_type()
145 membertype
= ': ' + typ
if typ
else ''
146 return '@item @code{%s%s}%s%s\n%s%s' % (
147 member
.name
, membertype
,
148 ' (optional)' if member
.optional
else '',
149 suffix
, desc
, texi_if(member
.ifcond
, prefix
='@*'))
152 def texi_members(doc
, what
, base
=None, variants
=None,
153 member_func
=texi_member
):
154 """Format the table of members"""
156 for section
in doc
.args
.values():
157 # TODO Drop fallbacks when undocumented members are outlawed
159 desc
= texi_format(section
.text
)
160 elif (variants
and variants
.tag_member
== section
.member
161 and not section
.member
.type.doc_type()):
162 values
= section
.member
.type.member_names()
163 members_text
= ', '.join(['@t{"%s"}' % v
for v
in values
])
164 desc
= 'One of ' + members_text
+ '\n'
166 desc
= 'Not documented\n'
167 items
+= member_func(section
.member
, desc
, suffix
='')
169 items
+= '@item The members of @code{%s}\n' % base
.doc_type()
171 for v
in variants
.variants
:
172 when
= ' when @code{%s} is @t{"%s"}%s' % (
173 variants
.tag_member
.name
, v
.name
, texi_if(v
.ifcond
, " (", ")"))
174 if v
.type.is_implicit():
175 assert not v
.type.base
and not v
.type.variants
176 for m
in v
.type.local_members
:
177 items
+= member_func(m
, desc
='', suffix
=when
)
179 items
+= '@item The members of @code{%s}%s\n' % (
180 v
.type.doc_type(), when
)
183 return '\n@b{%s:}\n@table @asis\n%s@end table\n' % (what
, items
)
186 def texi_arguments(doc
, boxed_arg_type
):
188 return ('\n@b{Arguments:} the members of @code{%s}\n'
189 % boxed_arg_type
.name
)
190 return texi_members(doc
, 'Arguments')
193 def texi_features(doc
):
194 """Format the table of features"""
196 for section
in doc
.features
.values():
197 desc
= texi_format(section
.text
)
198 items
+= '@item @code{%s}\n%s' % (section
.name
, desc
)
201 return '\n@b{Features:}\n@table @asis\n%s@end table\n' % (items
)
204 def texi_sections(doc
, ifcond
):
205 """Format additional sections following arguments"""
207 for section
in doc
.sections
:
209 # prefer @b over @strong, so txt doesn't translate it to *Foo:*
210 body
+= '\n@b{%s:}\n' % section
.name
211 if section
.name
and section
.name
.startswith('Example'):
212 body
+= texi_example(section
.text
)
214 body
+= texi_format(section
.text
)
215 body
+= texi_if(ifcond
, suffix
='')
219 def texi_type(typ
, doc
, ifcond
, members
):
220 return TYPE_FMT(type=typ
,
224 features
=texi_features(doc
),
225 sections
=texi_sections(doc
, ifcond
))
228 def texi_msg(typ
, doc
, ifcond
, members
):
229 return MSG_FMT(type=typ
,
233 features
=texi_features(doc
),
234 sections
=texi_sections(doc
, ifcond
))
237 class QAPISchemaGenDocVisitor(QAPISchemaVisitor
):
238 def __init__(self
, prefix
):
239 self
._prefix
= prefix
240 self
._gen
= QAPIGenDoc(self
._prefix
+ 'qapi-doc.texi')
243 def write(self
, output_dir
):
244 self
._gen
.write(output_dir
)
246 def visit_enum_type(self
, name
, info
, ifcond
, members
, prefix
):
248 self
._gen
.add(texi_type('Enum', doc
, ifcond
,
249 texi_members(doc
, 'Values',
250 member_func
=texi_enum_value
)))
252 def visit_object_type(self
, name
, info
, ifcond
, base
, members
, variants
,
255 if base
and base
.is_implicit():
257 self
._gen
.add(texi_type('Object', doc
, ifcond
,
258 texi_members(doc
, 'Members', base
, variants
)))
260 def visit_alternate_type(self
, name
, info
, ifcond
, variants
):
262 self
._gen
.add(texi_type('Alternate', doc
, ifcond
,
263 texi_members(doc
, 'Members')))
265 def visit_command(self
, name
, info
, ifcond
, arg_type
, ret_type
, gen
,
266 success_response
, boxed
, allow_oob
, allow_preconfig
,
269 self
._gen
.add(texi_msg('Command', doc
, ifcond
,
271 arg_type
if boxed
else None)))
273 def visit_event(self
, name
, info
, ifcond
, arg_type
, boxed
):
275 self
._gen
.add(texi_msg('Event', doc
, ifcond
,
277 arg_type
if boxed
else None)))
279 def symbol(self
, doc
, entity
):
286 def freeform(self
, doc
):
290 self
._gen
.add(texi_body(doc
) + texi_sections(doc
, None))
293 def gen_doc(schema
, output_dir
, prefix
):
294 vis
= QAPISchemaGenDocVisitor(prefix
)
295 vis
.visit_begin(schema
)
296 for doc
in schema
.docs
:
298 vis
.symbol(doc
, schema
.lookup_entity(doc
.symbol
))
301 vis
.write(output_dir
)