docs/devel/qapi-domain.rst

6 <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html>`_
10 <https://www.sphinx-doc.org/en/master/usage/domains/python.html>`_
16 <https://www.sphinx-doc.org/en/master/usage/domains/index.html>`_
17 provides a set of special rST directives and cross-referencing roles to
21 <https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html>`_
31 understanding the cross-referencing syntax *will* be helpful when
64 <https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#field-lists>`_
66 <https://www.sphinx-doc.org/en/master/usage/domains/python.html#info-field-lists>`_
68 example, add cross-references. The QAPI Domain takes advantage of this
81   * May apply cross-reference roles to *either* the argument *or* the
82     content body, both, or neither.
90     merged into one section, and the content will form a bulleted list.
92   * May optionally apply a cross-reference role to the argument, but not
96   * All items will be generated with the form: "argument -- body"
105     merged into one section, and the content will form a bulleted list.
106   * *Must* take at least one argument, but supports up to two -
108   * May optionally apply a cross-reference role to the type or the name
112   * All items will be generated with the form "name (type) -- body"
118 cross-referenced in the HTML output; or one of the built-in JSON types
123 ----------
139       Driver specific block device options for the virtio-blk-vhost-vdpa
142    :memb string path: path to the vhost-vdpa character device.
148 ---------
161    .. qapi:command:: job-pause
179 -----------
189 The format of the :errors: field list description is free-form rST. The
195    .. qapi:command:: block-job-set-speed
198       Set maximum speed for a background block operation.
210           - If no background operation is active on this device,
215 -------------
228    .. qapi:command:: query-replay
232       instruction count which may be used for ``replay-break`` and
233       ``replay-seek`` commands.
237       .. qmp-example::
239           -> { "execute": "query-replay" }
240           <- { "return": {
246 -----------
273 ------------
302 ----------
327 ---------------------
331 list names. If you want to add a new arbitrary "non-value-added" field
343    .. qapi:command:: x-fake-command
348 Cross-references
351 Cross-reference `roles
352 <https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html>`_
354 cross-referencing syntax
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>`_
359 role cross-reference syntax, such as with ```query-blockstats```.  In
360 the event that disambiguation is needed, cross-references can also be
361 written using a number of explicit cross-reference roles:
363 * ``:qapi:mod:`block-core``` -- Reference a QAPI module. The link will
365 * ``:qapi:cmd:`query-block``` -- Reference a QAPI command.
366 * ``:qapi:event:`JOB_STATUS_CHANGE``` -- Reference a QAPI event.
367 * ``:qapi:enum:`QapiErrorClass``` -- Reference a QAPI enum.
368 * ``:qapi:obj:`BlockdevOptionsVirtioBlkVhostVdpa`` -- Reference a QAPI
370 * ``:qapi:alt:`StrOrNull``` -- Reference a QAPI alternate.
371 * ``:qapi:type:`BlockDirtyInfo``` -- Reference *any* QAPI type; this
373 * ``:qapi:any:`block-job-set-speed``` -- Reference absolutely any QAPI entity.
378 cross-references.
382 ----------------
385 ``[typename]``, to indicate an array of that type.  The cross-reference
391 can be suffixed with ``?``. The cross-reference will be transformed to
398 ----------
401 <https://www.sphinx-doc.org/en/master/usage/domains/python.html#target-specification>`_,
408   ``:qapi:type:`QMP:block-core.BitmapSyncMode``` will render to:
409   :qapi:type:`QMP:block-core.BitmapSyncMode`
411   prefixed with a tilde; ``:qapi:type:`~QMP:block-core.BitmapSyncMode```
412   will render to: :qapi:type:`~QMP:block-core.BitmapSyncMode`
416 -----------------
418 Any cross-reference to a QAPI type, whether using the ```any``` style of
425 cross-reference.
431 This allows for efficient cross-referencing with a minimum of syntax in
438 ----------------
440 The name of a cross-reference link can be explicitly overridden like
442 <https://www.sphinx-doc.org/en/master/usage/referencing.html#syntax>`_
446 <block-dirty-bitmap-merge>``` will render as: :qapi:cmd:`Merge dirty
447 bitmaps <QMP:block-dirty-bitmap-merge>`
459      :another-option: with an argument
461      Content body, arbitrary rST is allowed here.
465 -----------------------
468 <https://www.sphinx-doc.org/en/master/usage/domains/index.html#basic-markup>`_
475 * ``:no-index:`` and ``:noindex:`` -- Do not add this item into the
476   Index, and do not make it available for cross-referencing.
477 * ``no-index-entry:`` and ``:noindexentry:`` -- Do not add this item
478   into the Index, but allow it to be cross-referenced.
479 * ``no-contents-entry`` and ``:nocontentsentry:`` -- Exclude this item
481 * ``no-typesetting`` -- Create TOC, Index and cross-referencing
482   entities, but don't actually display the content.
486 ---------------------
488 All QAPI directives -- *except* for namespace and module -- support
491 * ``:namespace: name`` -- This option allows you to override the
493 * ``:module: modname`` -- Borrowed from the Python domain, this option allows
495 * ``:since: x.y`` -- Allows the documenting of "Since" information, which is
497 * ``:ifcond: CONDITION`` -- Allows the documenting of conditional availability
500 * ``:deprecated:`` -- Adds an eyecatch just below the signature bar that
502 * ``:unstable:`` -- Adds an eyecatch just below the signature bar that
508 --------------
511 does not take a content body, nor any options. All subsequent QAPI
530 -----------
533 a content body, but it can be omitted. All subsequent QAPI directives
539    .. qapi:module:: block-core
541       Welcome to the block-core module!
545 .. qapi:module:: block-core
548    Welcome to the block-core module!
552 ------------
561   .. qapi:command:: x-fake-command
569      :return [string]: A lovely computer-written poem for you.
574   .. qapi:command:: x-fake-command
583      :return [string]: A lovely computer-written poem for you.
587 ----------
622 ---------
635      :value Happy: Your VM is content and well-fed.
648    :value Happy: Your VM is content and well-fed.
655 -----------
670      :memb [string] Fav-Foods: A list of your favorite foods.
671      :memb boolean? Bizarre-Docs: True if the documentation reference
683    :memb [string] Fav-Foods: A list of your favorite foods.
684    :memb boolean? Bizarre-Docs: True if the documentation reference
689 --------------
702      :alt string em: An expletive-laced error message, if your
714    :alt string em: An expletive-laced error message, if your