]>
Commit | Line | Data |
---|---|---|
3313b612 MAL |
1 | #!/usr/bin/env python |
2 | # QAPI texi generator | |
3 | # | |
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""" | |
7 | import re | |
8 | import sys | |
9 | ||
10 | import qapi | |
11 | ||
597494ab | 12 | MSG_FMT = """ |
3313b612 MAL |
13 | @deftypefn {type} {{}} {name} |
14 | ||
15 | {body} | |
16 | ||
17 | @end deftypefn | |
18 | ||
19 | """.format | |
20 | ||
597494ab | 21 | TYPE_FMT = """ |
3313b612 MAL |
22 | @deftp {{{type}}} {name} |
23 | ||
24 | {body} | |
25 | ||
26 | @end deftp | |
27 | ||
28 | """.format | |
29 | ||
30 | EXAMPLE_FMT = """@example | |
31 | {code} | |
32 | @end example | |
33 | """.format | |
34 | ||
35 | ||
36 | def subst_strong(doc): | |
37 | """Replaces *foo* by @strong{foo}""" | |
38 | return re.sub(r'\*([^*\n]+)\*', r'@emph{\1}', doc) | |
39 | ||
40 | ||
41 | def subst_emph(doc): | |
42 | """Replaces _foo_ by @emph{foo}""" | |
43 | return re.sub(r'\b_([^_\n]+)_\b', r' @emph{\1} ', doc) | |
44 | ||
45 | ||
46 | def subst_vars(doc): | |
47 | """Replaces @var by @code{var}""" | |
48 | return re.sub(r'@([\w-]+)', r'@code{\1}', doc) | |
49 | ||
50 | ||
51 | def subst_braces(doc): | |
52 | """Replaces {} with @{ @}""" | |
ef801a9b | 53 | return doc.replace('{', '@{').replace('}', '@}') |
3313b612 MAL |
54 | |
55 | ||
56 | def texi_example(doc): | |
57 | """Format @example""" | |
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) | |
64 | ||
65 | ||
66 | def texi_format(doc): | |
67 | """ | |
68 | Format documentation | |
69 | ||
70 | Lines starting with: | |
71 | - |: generates an @example | |
72 | - =: generates @section | |
73 | - ==: generates @subsection | |
74 | - 1. or 1): generates an @enumerate @item | |
75 | - */-: generates an @itemize list | |
76 | """ | |
77 | lines = [] | |
78 | doc = subst_braces(doc) | |
79 | doc = subst_vars(doc) | |
80 | doc = subst_emph(doc) | |
81 | doc = subst_strong(doc) | |
ef801a9b | 82 | inlist = '' |
3313b612 MAL |
83 | lastempty = False |
84 | for line in doc.split('\n'): | |
ef801a9b | 85 | empty = line == '' |
3313b612 MAL |
86 | |
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 | |
91 | # doesn't. | |
92 | # | |
93 | # Make sure to update section "Documentation markup" in | |
94 | # docs/qapi-code-gen.txt when fixing this. | |
ef801a9b | 95 | if line.startswith('| '): |
3313b612 | 96 | line = EXAMPLE_FMT(code=line[2:]) |
ef801a9b MA |
97 | elif line.startswith('= '): |
98 | line = '@section ' + line[2:] | |
99 | elif line.startswith('== '): | |
100 | line = '@subsection ' + line[3:] | |
3313b612 MAL |
101 | elif re.match(r'^([0-9]*\.) ', line): |
102 | if not inlist: | |
ef801a9b MA |
103 | lines.append('@enumerate') |
104 | inlist = 'enumerate' | |
105 | line = line[line.find(' ')+1:] | |
106 | lines.append('@item') | |
3313b612 MAL |
107 | elif re.match(r'^[*-] ', line): |
108 | if not inlist: | |
ef801a9b MA |
109 | lines.append('@itemize %s' % {'*': '@bullet', |
110 | '-': '@minus'}[line[0]]) | |
111 | inlist = 'itemize' | |
112 | lines.append('@item') | |
3313b612 MAL |
113 | line = line[2:] |
114 | elif lastempty and inlist: | |
ef801a9b MA |
115 | lines.append('@end %s\n' % inlist) |
116 | inlist = '' | |
3313b612 MAL |
117 | |
118 | lastempty = empty | |
119 | lines.append(line) | |
120 | ||
121 | if inlist: | |
ef801a9b MA |
122 | lines.append('@end %s\n' % inlist) |
123 | return '\n'.join(lines) | |
3313b612 MAL |
124 | |
125 | ||
aa964b7f MA |
126 | def texi_body(doc): |
127 | """Format the main documentation body""" | |
128 | return texi_format(str(doc.body)) + '\n' | |
129 | ||
130 | ||
131 | def texi_enum_value(value): | |
132 | """Format a table of members item for an enumeration value""" | |
71d918a1 | 133 | return '@item @code{%s}\n' % value.name |
aa964b7f MA |
134 | |
135 | ||
136 | def texi_member(member): | |
137 | """Format a table of members item for an object type member""" | |
71d918a1 | 138 | return '@item @code{%s}%s\n' % ( |
aa964b7f MA |
139 | member.name, ' (optional)' if member.optional else '') |
140 | ||
3313b612 | 141 | |
2a1183ce | 142 | def texi_members(doc, what, member_func, show_undocumented): |
aa964b7f MA |
143 | """Format the table of members""" |
144 | items = '' | |
145 | for section in doc.args.itervalues(): | |
146 | if not section.content and not show_undocumented: | |
147 | continue # Undocumented TODO require doc and drop | |
5da19f14 MA |
148 | if section.content: |
149 | desc = str(section) | |
150 | else: | |
151 | desc = 'Not documented' | |
aa964b7f MA |
152 | items += member_func(section.member) + texi_format(desc) + '\n' |
153 | if not items: | |
154 | return '' | |
2a1183ce | 155 | return '\n@b{%s:}\n@table @asis\n%s@end table\n' % (what, items) |
aa964b7f MA |
156 | |
157 | ||
158 | def texi_sections(doc): | |
159 | """Format additional sections following arguments""" | |
160 | body = '' | |
3313b612 MAL |
161 | for section in doc.sections: |
162 | name, doc = (section.name, str(section)) | |
163 | func = texi_format | |
ef801a9b | 164 | if name.startswith('Example'): |
3313b612 MAL |
165 | func = texi_example |
166 | ||
167 | if name: | |
1ede77df | 168 | # prefer @b over @strong, so txt doesn't translate it to *Foo:* |
ef801a9b | 169 | body += '\n\n@b{%s:}\n' % name |
1ede77df MAL |
170 | |
171 | body += func(doc) | |
3313b612 MAL |
172 | return body |
173 | ||
174 | ||
2a1183ce MA |
175 | def texi_entity(doc, what, member_func=texi_member, |
176 | show_undocumented=False): | |
aa964b7f | 177 | return (texi_body(doc) |
2a1183ce | 178 | + texi_members(doc, what, member_func, show_undocumented) |
aa964b7f MA |
179 | + texi_sections(doc)) |
180 | ||
181 | ||
182 | class QAPISchemaGenDocVisitor(qapi.QAPISchemaVisitor): | |
183 | def __init__(self): | |
184 | self.out = None | |
185 | self.cur_doc = None | |
186 | ||
187 | def visit_begin(self, schema): | |
188 | self.out = '' | |
189 | ||
190 | def visit_enum_type(self, name, info, values, prefix): | |
191 | doc = self.cur_doc | |
192 | if self.out: | |
193 | self.out += '\n' | |
194 | self.out += TYPE_FMT(type='Enum', | |
195 | name=doc.symbol, | |
2a1183ce | 196 | body=texi_entity(doc, 'Values', |
aa964b7f MA |
197 | member_func=texi_enum_value, |
198 | show_undocumented=True)) | |
199 | ||
200 | def visit_object_type(self, name, info, base, members, variants): | |
201 | doc = self.cur_doc | |
202 | if not variants: | |
203 | typ = 'Struct' | |
204 | elif variants._tag_name: # TODO unclean member access | |
205 | typ = 'Flat Union' | |
206 | else: | |
207 | typ = 'Simple Union' | |
208 | if self.out: | |
209 | self.out += '\n' | |
210 | self.out += TYPE_FMT(type=typ, | |
211 | name=doc.symbol, | |
2a1183ce | 212 | body=texi_entity(doc, 'Members')) |
aa964b7f MA |
213 | |
214 | def visit_alternate_type(self, name, info, variants): | |
215 | doc = self.cur_doc | |
216 | if self.out: | |
217 | self.out += '\n' | |
218 | self.out += TYPE_FMT(type='Alternate', | |
219 | name=doc.symbol, | |
2a1183ce | 220 | body=texi_entity(doc, 'Members')) |
aa964b7f MA |
221 | |
222 | def visit_command(self, name, info, arg_type, ret_type, | |
223 | gen, success_response, boxed): | |
224 | doc = self.cur_doc | |
225 | if self.out: | |
226 | self.out += '\n' | |
227 | self.out += MSG_FMT(type='Command', | |
228 | name=doc.symbol, | |
2a1183ce | 229 | body=texi_entity(doc, 'Arguments')) |
aa964b7f MA |
230 | |
231 | def visit_event(self, name, info, arg_type, boxed): | |
232 | doc = self.cur_doc | |
233 | if self.out: | |
234 | self.out += '\n' | |
235 | self.out += MSG_FMT(type='Event', | |
236 | name=doc.symbol, | |
2a1183ce | 237 | body=texi_entity(doc, 'Arguments')) |
aa964b7f MA |
238 | |
239 | def symbol(self, doc, entity): | |
240 | self.cur_doc = doc | |
241 | entity.visit(self) | |
242 | self.cur_doc = None | |
243 | ||
244 | def freeform(self, doc): | |
245 | assert not doc.args | |
246 | if self.out: | |
247 | self.out += '\n' | |
248 | self.out += texi_body(doc) + texi_sections(doc) | |
249 | ||
250 | ||
251 | def texi_schema(schema): | |
252 | """Convert QAPI schema documentation to Texinfo""" | |
253 | gen = QAPISchemaGenDocVisitor() | |
254 | gen.visit_begin(schema) | |
255 | for doc in schema.docs: | |
256 | if doc.symbol: | |
257 | gen.symbol(doc, schema.lookup_entity(doc.symbol)) | |
258 | else: | |
259 | gen.freeform(doc) | |
260 | return gen.out | |
3313b612 MAL |
261 | |
262 | ||
263 | def main(argv): | |
264 | """Takes schema argument, prints result to stdout""" | |
265 | if len(argv) != 2: | |
266 | print >>sys.stderr, "%s: need exactly 1 argument: SCHEMA" % argv[0] | |
267 | sys.exit(1) | |
268 | ||
269 | schema = qapi.QAPISchema(argv[1]) | |
bc52d03f MA |
270 | if not qapi.doc_required: |
271 | print >>sys.stderr, ("%s: need pragma 'doc-required' " | |
272 | "to generate documentation" % argv[0]) | |
aa964b7f | 273 | print texi_schema(schema) |
3313b612 MAL |
274 | |
275 | ||
ef801a9b | 276 | if __name__ == '__main__': |
3313b612 | 277 | main(sys.argv) |