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>`_
253 :type: `sphinx.util.docfields.GroupedField
254        <https://pydoc.dev/sphinx/latest/sphinx.util.docfields.GroupedField.html?private=1>`_
280 :type: `sphinx.util.docfields.TypedField
281        <https://pydoc.dev/sphinx/latest/sphinx.util.docfields.TypedField.html?private=1>`_
283 As a limitation of Sphinx, we must document the "name" of the branch in
309 :type: `sphinx.util.docfields.TypedField
310        <https://pydoc.dev/sphinx/latest/sphinx.util.docfields.TypedField.html?private=1>`_
352 <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html>`_
355 <https://www.sphinx-doc.org/en/master/usage/domains/python.html#cross-referencing-python-objects>`_.
358 <https://www.sphinx-doc.org/en/master/usage/referencing.html#role-any>`_
401 <https://www.sphinx-doc.org/en/master/usage/domains/python.html#target-specification>`_,
441 `most stock Sphinx references
442 <https://www.sphinx-doc.org/en/master/usage/referencing.html#syntax>`_
464 Sphinx standard options
468 <https://www.sphinx-doc.org/en/master/usage/domains/index.html#basic-markup>`_
469 from Sphinx's ObjectDescription class.
471 The dashed spellings of the below options were added in Sphinx 7.2, the
555 Sphinx or QAPI options, and the documentation body may contain
590 Sphinx or QAPI options, and the documentation body may contain
625 Sphinx or QAPI options, and the documentation body may contain
658 object. It may use any of the standard Sphinx or QAPI options, and the
692 standard Sphinx or QAPI options, and the documentation body may contain