docs/devel/qapi-domain.rst

2 The Sphinx QAPI Domain
6 <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_
7 in Sphinx is provided by the QAPI Domain, located in
8 ``docs/sphinx/qapi_domain.py``. This extension is analogous to the
10 <https://www.sphinx-doc.org/en/master/usage/domains/python.html>`_
11 included with Sphinx, but provides special directives and roles
16 <https://www.sphinx-doc.org/en/master/usage/domains/index.html>`_
18 Sphinx for understanding rST markup written to document a specific
21 <https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html>`_
22 functionality is provided elsewhere, in ``docs/sphinx/qapidoc.py``, by
41 the rST syntax used to describe things. For instance, the Sphinx Python
47 syntax and providing APIs for Sphinx internals.
51 qapi_domain.py adds syntax like ``.. qapi:command::`` to Sphinx, and
64 <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#field-lists>`_
65 are a standard syntax in reStructuredText. Sphinx `extends that syntax
66 <https://www.sphinx-doc.org/en/master/usage/domains/python.html#info-field-lists>`_
72 The special parsing and handling of info field lists in Sphinx is provided by
130 :type: `sphinx.util.docfields.GroupedField
131        <https://pydoc.dev/sphinx/latest/sphinx.util.docfields.GroupedField.html?private=1>`_
155 :type: `sphinx.util.docfields.TypedField
156        <https://pydoc.dev/sphinx/latest/sphinx.util.docfields.TypedField.html?private=1>`_
186 :type: `sphinx.util.docfields.Field
187        <https://pydoc.dev/sphinx/latest/sphinx.util.docfields.Field.html?private=1>`_
222 :type: `sphinx.util.docfields.GroupedField
223        <https://pydoc.dev/sphinx/latest/sphinx.util.docfields.GroupedField.html?private=1>`_
254 :type: `sphinx.util.docfields.Field
255        <https://pydoc.dev/sphinx/latest/sphinx.util.docfields.Field.html?private=1>`_
284 :type: `sphinx.util.docfields.GroupedField
285        <https://pydoc.dev/sphinx/latest/sphinx.util.docfields.GroupedField.html?private=1>`_
311 :type: `sphinx.util.docfields.TypedField
312        <https://pydoc.dev/sphinx/latest/sphinx.util.docfields.TypedField.html?private=1>`_
314 As a limitation of Sphinx, we must document the "name" of the branch in
340 :type: `sphinx.util.docfields.TypedField
341        <https://pydoc.dev/sphinx/latest/sphinx.util.docfields.TypedField.html?private=1>`_
384 <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html>`_
387 <https://www.sphinx-doc.org/en/master/usage/domains/python.html#cross-referencing-python-objects>`_.
390 <https://www.sphinx-doc.org/en/master/usage/referencing.html#role-any>`_
433 <https://www.sphinx-doc.org/en/master/usage/domains/python.html#target-specification>`_,
473 `most stock Sphinx references
474 <https://www.sphinx-doc.org/en/master/usage/referencing.html#syntax>`_
496 Sphinx standard options
500 <https://www.sphinx-doc.org/en/master/usage/domains/index.html#basic-markup>`_
501 from Sphinx's ObjectDescription class.
503 The dashed spellings of the below options were added in Sphinx 7.2, the
587 Sphinx or QAPI options, and the documentation body may contain
622 Sphinx or QAPI options, and the documentation body may contain
657 Sphinx or QAPI options, and the documentation body may contain
690 object. It may use any of the standard Sphinx or QAPI options, and the
724 standard Sphinx or QAPI options, and the documentation body may contain