]>
git.proxmox.com Git - mirror_qemu.git/blob - scripts/qapi2texi.py
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
'@emph{\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/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
)
128 Format the body of a symbol documentation:
131 - followed by "Returns/Notes/Since/Example" sections
133 body
= texi_format(str(doc
.body
)) + "\n"
135 body
+= "@table @asis\n"
136 for arg
, section
in doc
.args
.iteritems():
139 if "#optional" in desc
:
140 desc
= re
.sub(r
'^ *#optional *\n?|\n? *#optional *$|#optional',
143 body
+= "@item @code{'%s'}%s\n%s\n" % (arg
, opt
,
145 body
+= "@end table\n"
147 for section
in doc
.sections
:
148 name
, doc
= (section
.name
, str(section
))
150 if name
.startswith("Example"):
154 # prefer @b over @strong, so txt doesn't translate it to *Foo:*
155 body
+= "\n\n@b{%s:}\n" % name
162 def texi_alternate(expr
, doc
):
163 """Format an alternate to texi"""
164 body
= texi_body(doc
)
165 return TYPE_FMT(type="Alternate",
170 def texi_union(expr
, doc
):
171 """Format a union to texi"""
172 discriminator
= expr
.get("discriminator")
176 union
= "Simple Union"
178 body
= texi_body(doc
)
179 return TYPE_FMT(type=union
,
184 def texi_enum(expr
, doc
):
185 """Format an enum to texi"""
186 for i
in expr
['data']:
187 if i
not in doc
.args
:
189 body
= texi_body(doc
)
190 return TYPE_FMT(type="Enum",
195 def texi_struct(expr
, doc
):
196 """Format a struct to texi"""
197 body
= texi_body(doc
)
198 return TYPE_FMT(type="Struct",
203 def texi_command(expr
, doc
):
204 """Format a command to texi"""
205 body
= texi_body(doc
)
206 return MSG_FMT(type="Command",
211 def texi_event(expr
, doc
):
212 """Format an event to texi"""
213 body
= texi_body(doc
)
214 return MSG_FMT(type="Event",
219 def texi_expr(expr
, doc
):
220 """Format an expr to texi"""
221 (kind
, _
) = expr
.items()[0]
223 fmt
= {"command": texi_command
,
224 "struct": texi_struct
,
227 "alternate": texi_alternate
,
228 "event": texi_event
}[kind
]
230 return fmt(expr
, doc
)
234 """Convert QAPI schema expressions to texi documentation"""
239 res
.append(texi_body(doc
))
242 doc
= texi_expr(expr
, doc
)
245 print >>sys
.stderr
, "error at @%s" % doc
.info
248 return '\n'.join(res
)
252 """Takes schema argument, prints result to stdout"""
254 print >>sys
.stderr
, "%s: need exactly 1 argument: SCHEMA" % argv
[0]
257 schema
= qapi
.QAPISchema(argv
[1])
258 if not qapi
.doc_required
:
259 print >>sys
.stderr
, ("%s: need pragma 'doc-required' "
260 "to generate documentation" % argv
[0])
261 print texi(schema
.docs
)
264 if __name__
== "__main__":