4 # This work is licensed under the terms of the GNU LGPL, version 2+.
5 # See the COPYING file in the top-level directory.
6 """This script produces the documentation of a qapi schema in texinfo format"""
13 @deftypefn {type} {{}} {name}
22 @deftp {{{type}}} {name}
30 EXAMPLE_FMT
= """@example
36 def subst_strong(doc
):
37 """Replaces *foo* by @strong{foo}"""
38 return re
.sub(r
'\*([^*\n]+)\*', r
'@strong{\1}', doc
)
42 """Replaces _foo_ by @emph{foo}"""
43 return re
.sub(r
'\b_([^_\n]+)_\b', r
'@emph{\1}', doc
)
47 """Replaces @var by @code{var}"""
48 return re
.sub(r
'@([\w-]+)', r
'@code{\1}', doc
)
51 def subst_braces(doc
):
52 """Replaces {} with @{ @}"""
53 return doc
.replace('{', '@{').replace('}', '@}')
56 def texi_example(doc
):
58 # TODO: Neglects to escape @ characters.
59 # We should probably escape them in subst_braces(), and rename the
60 # function to subst_special() or subs_texi_special(). If we do that, we
61 # need to delay it until after subst_vars() in texi_format().
62 doc
= subst_braces(doc
).strip('\n')
63 return EXAMPLE_FMT(code
=doc
)
71 - |: generates an @example
72 - =: generates @section
73 - ==: generates @subsection
74 - 1. or 1): generates an @enumerate @item
75 - */-: generates an @itemize list
78 doc
= subst_braces(doc
)
81 doc
= subst_strong(doc
)
84 for line
in doc
.split('\n'):
87 # FIXME: Doing this in a single if / elif chain is
88 # problematic. For instance, a line without markup terminates
89 # a list if it follows a blank line (reaches the final elif),
90 # but a line with some *other* markup, such as a = title
93 # Make sure to update section "Documentation markup" in
94 # docs/devel/qapi-code-gen.txt when fixing this.
95 if line
.startswith('| '):
96 line
= EXAMPLE_FMT(code
=line
[2:])
97 elif line
.startswith('= '):
98 line
= '@section ' + line
[2:]
99 elif line
.startswith('== '):
100 line
= '@subsection ' + line
[3:]
101 elif re
.match(r
'^([0-9]*\.) ', line
):
103 lines
.append('@enumerate')
105 line
= line
[line
.find(' ')+1:]
106 lines
.append('@item')
107 elif re
.match(r
'^[*-] ', line
):
109 lines
.append('@itemize %s' % {'*': '@bullet',
110 '-': '@minus'}[line
[0]])
112 lines
.append('@item')
114 elif lastempty
and inlist
:
115 lines
.append('@end %s\n' % inlist
)
122 lines
.append('@end %s\n' % inlist
)
123 return '\n'.join(lines
)
127 """Format the main documentation body"""
128 return texi_format(str(doc
.body
)) + '\n'
131 def texi_enum_value(value
):
132 """Format a table of members item for an enumeration value"""
133 return '@item @code{%s}\n' % value
.name
136 def texi_member(member
, suffix
=''):
137 """Format a table of members item for an object type member"""
138 typ
= member
.type.doc_type()
139 return '@item @code{%s%s%s}%s%s\n' % (
143 ' (optional)' if member
.optional
else '',
147 def texi_members(doc
, what
, base
, variants
, member_func
):
148 """Format the table of members"""
150 for section
in doc
.args
.itervalues():
151 # TODO Drop fallbacks when undocumented members are outlawed
153 desc
= texi_format(str(section
))
154 elif (variants
and variants
.tag_member
== section
.member
155 and not section
.member
.type.doc_type()):
156 values
= section
.member
.type.member_names()
157 desc
= 'One of ' + ', '.join(['@t{"%s"}' % v
for v
in values
])
159 desc
= 'Not documented'
160 items
+= member_func(section
.member
) + desc
+ '\n'
162 items
+= '@item The members of @code{%s}\n' % base
.doc_type()
164 for v
in variants
.variants
:
165 when
= ' when @code{%s} is @t{"%s"}' % (
166 variants
.tag_member
.name
, v
.name
)
167 if v
.type.is_implicit():
168 assert not v
.type.base
and not v
.type.variants
169 for m
in v
.type.local_members
:
170 items
+= member_func(m
, when
)
172 items
+= '@item The members of @code{%s}%s\n' % (
173 v
.type.doc_type(), when
)
176 return '\n@b{%s:}\n@table @asis\n%s@end table\n' % (what
, items
)
179 def texi_sections(doc
):
180 """Format additional sections following arguments"""
182 for section
in doc
.sections
:
184 # prefer @b over @strong, so txt doesn't translate it to *Foo:*
185 body
+= '\n\n@b{%s:}\n' % section
.name
187 if section
.name
and section
.name
.startswith('Example'):
188 body
+= texi_example(text
)
190 body
+= texi_format(text
)
194 def texi_entity(doc
, what
, base
=None, variants
=None,
195 member_func
=texi_member
):
196 return (texi_body(doc
)
197 + texi_members(doc
, what
, base
, variants
, member_func
)
198 + texi_sections(doc
))
201 class QAPISchemaGenDocVisitor(qapi
.QAPISchemaVisitor
):
206 def visit_begin(self
, schema
):
209 def visit_enum_type(self
, name
, info
, values
, prefix
):
213 self
.out
+= TYPE_FMT(type='Enum',
215 body
=texi_entity(doc
, 'Values',
216 member_func
=texi_enum_value
))
218 def visit_object_type(self
, name
, info
, base
, members
, variants
):
220 if base
and base
.is_implicit():
224 self
.out
+= TYPE_FMT(type='Object',
226 body
=texi_entity(doc
, 'Members', base
, variants
))
228 def visit_alternate_type(self
, name
, info
, variants
):
232 self
.out
+= TYPE_FMT(type='Alternate',
234 body
=texi_entity(doc
, 'Members'))
236 def visit_command(self
, name
, info
, arg_type
, ret_type
,
237 gen
, success_response
, boxed
):
242 body
= texi_body(doc
)
243 body
+= '\n@b{Arguments:} the members of @code{%s}' % arg_type
.name
244 body
+= texi_sections(doc
)
246 body
= texi_entity(doc
, 'Arguments')
247 self
.out
+= MSG_FMT(type='Command',
251 def visit_event(self
, name
, info
, arg_type
, boxed
):
255 self
.out
+= MSG_FMT(type='Event',
257 body
=texi_entity(doc
, 'Arguments'))
259 def symbol(self
, doc
, entity
):
264 def freeform(self
, doc
):
268 self
.out
+= texi_body(doc
) + texi_sections(doc
)
271 def texi_schema(schema
):
272 """Convert QAPI schema documentation to Texinfo"""
273 gen
= QAPISchemaGenDocVisitor()
274 gen
.visit_begin(schema
)
275 for doc
in schema
.docs
:
277 gen
.symbol(doc
, schema
.lookup_entity(doc
.symbol
))
284 """Takes schema argument, prints result to stdout"""
286 print >>sys
.stderr
, "%s: need exactly 1 argument: SCHEMA" % argv
[0]
289 schema
= qapi
.QAPISchema(argv
[1])
290 if not qapi
.doc_required
:
291 print >>sys
.stderr
, ("%s: need pragma 'doc-required' "
292 "to generate documentation" % argv
[0])
294 print texi_schema(schema
)
297 if __name__
== '__main__':