docs/sphinx/qapidoc_legacy.py

8 # This work is licensed under the terms of the GNU GPLv2 or later.
9 # See the COPYING file in the top-level directory.
12 qapidoc is a Sphinx extension that implements the qapi-doc directive
14 The purpose of this extension is to read the documentation comments
15 in QAPI schema files, and insert them all into the current document.
18 Each qapi-doc:: directive takes one argument, which is the
19 pathname of the schema file to process, relative to the source tree.
21 The docs/conf.py file must set the qapidoc_srctree config value to
22 the root of the QEMU source tree.
24 The Sphinx documentation on writing extensions is at:
43         # First line is indented; description started on the line after
44         # the name. dedent the whole block.
55     to documentation for the various QAPI objects. To use it, first
57     visit_begin() method.  Then you can call one of the two methods
60     will cause the visitor to build up the tree of document
61     nodes. Once you've added all the documentation via 'freeform' and
63     the final list of document nodes (in a form suitable for returning
73         """Return a dlitem node with the specified term and definition.
101         """Return list of Text, literal nodes for the ifcond
104         If with_if is False, we don't return the "(If: " and ")".
123         'name: type (optional) (If: ...)' suitable for use as the
141         the 'branches' part of a definition list.
152         """Return list of doctree nodes for the table of members"""
165             dlnode += self._make_dlitem([nodes.Text('The members of '),
174                 term = [nodes.Text('The members of '),
187         """Return list of doctree nodes for the table of enum values"""
211         """Return list of doctree nodes for the arguments section"""
217                 [nodes.Text('The members of '),
226         """Return list of doctree nodes for the table of features"""
251                 # Instead, just append the results to the prior section.
263         """Return list of doctree nodes for the "If" section"""
276         We assume we're documenting the thing defined in self._cur_doc.
277         typ is the type of thing being added ("Command", "Object", etc)
279         sections is a list of nodes for sections to add to the definition.
339         """Add documentation for one symbol to the document tree
341         This is the main entry point which causes us to add documentation
343         etc). We do this by calling 'visit' on the schema entity, which
352         """Start a new heading at the specified heading level
355         in the docutils node tree as a child of the most recent level-1
371         """Add the node to whatever the current active heading is"""
375         """Add a piece of 'freeform' documentation to the document tree
380         If the freeform document starts with a line of the form
382         the heading level indicated by the number of '=' signs.
395             # the first line of the block)
408         """Parse a chunk of QAPI-doc-format text into the node
410         The doc comment can contain most inline rST markup, including
416         # Handle the "@var means ``var`` case
421             # The reported line number will always be that of the start line
422             # of the doc comment, rather than the actual location of the error.
423             # Being more precise would require overhaul of the QAPIDoc class
424             # to track lines more exactly within all the sub-parts of the doc
429         # attributed to the line after one with actual text, and if there
430         # isn't anything in the ViewList corresponding to that then Sphinx
431         # 1.6's AutodocReporter will then misidentify the source/line location
432         # in the error message (usually attributing it to the top-level
433         # .rst file rather than the offending .json file). The extra blank
434         # line won't affect the rendered output.
439         """Return the root docutils node which makes up the document"""