docs/sphinx/qapidoc.py

33 from docutils import nodes
44 from sphinx.util.nodes import nested_parse_with_titles
68     """A QAPI schema visitor which generates docutils/Sphinx nodes
70     This class builds up a tree of docutils/Sphinx nodes corresponding
77     nodes. Once you've added all the documentation via 'freeform' and
79     the final list of document nodes (in a form suitable for returning
85         self._top_node = nodes.section()
91         term should be a list of Text and literal nodes.
94         - a list of Text and literal nodes, which will be put into
97         dlitem = nodes.definition_list_item()
98         dlterm = nodes.term('', '', *term)
101             dldef = nodes.definition()
103                 dldef += nodes.paragraph('', '', *defn)
111         section = nodes.section(ids=[self._sphinx_directive.new_serialno()])
113             section += nodes.title(title, title)
117         """Return list of Text, literal nodes for the ifcond
126         doc = nodes.literal('', doc)
130         nodelist = [nodes.Text(' ('), nodes.strong('', 'If: ')]
132         nodelist.append(nodes.Text(')'))
136         """Return list of Text, literal nodes for this member
138         Return a list of doctree nodes which give text like
142         term = [nodes.literal('', member.name)]
144             term.append(nodes.Text(': '))
145             term.append(nodes.literal('', member.type.doc_type()))
147             term.append(nodes.Text(' (optional)'))
153         """Return list of Text, literal nodes for variant 'when' clause
155         Return a list of doctree nodes which give text like
159         term = [nodes.Text(' when '),
160                 nodes.literal('', branches.tag_member.name),
161                 nodes.Text(' is '),
162                 nodes.literal('', '"%s"' % variant.name)]
168         """Return list of doctree nodes for the table of members"""
169         dlnode = nodes.definition_list()
176                 defn = [nodes.Text('Not documented')]
181             dlnode += self._make_dlitem([nodes.Text('The members of '),
182                                          nodes.literal('', base.doc_type())],
190                 term = [nodes.Text('The members of '),
191                         nodes.literal('', v.type.doc_type())]
203         """Return list of doctree nodes for the table of enum values"""
205         dlnode = nodes.definition_list()
207             termtext = [nodes.literal('', section.member.name)]
214                 defn = [nodes.Text('Not documented')]
227         """Return list of doctree nodes for the arguments section"""
231             dlnode = nodes.definition_list()
233                 [nodes.Text('The members of '),
234                  nodes.literal('', arg_type.name)],
242         """Return list of doctree nodes for the table of features"""
244         dlnode = nodes.definition_list()
247                 [nodes.literal('', section.member.name)], dedent(section.text))
258         """Return list of doctree nodes for a code example snippet"""
259         return [nodes.literal_block(exampletext, exampletext)]
262         """Return list of doctree nodes for additional sections"""
272                 container = nodes.container()
286         """Return list of doctree nodes for the "If" section"""
290             snode += nodes.paragraph(
302         sections is a list of nodes for sections to add to the definition.
306         snode = nodes.section(ids=[self._sphinx_directive.new_serialno()])
307         snode += nodes.title('', '', *[nodes.literal(doc.symbol, doc.symbol),
308                                        nodes.Text(' (' + typ + ')')])
365         nodes for a symbol (which could be a 'command', 'object', 'event',
460         """Return the list of docutils nodes which make up the document"""
496         rST, and add the resulting docutils nodes as children of node.
497         The nodes are parsed in a way that allows them to include
593     def admonition_wrap(self, *content) -> List[nodes.Node]:
598         admon = nodes.admonition(
600             nodes.title("", title),
606     def run_annotated(self) -> List[nodes.Node]:
609         content_node: nodes.Element = nodes.section()
627     def run(self) -> List[nodes.Node]: