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
55 Or even shorter:
60 Info Field Lists
63 `Field lists
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>`_
67 to give certain field list entries special meaning and parsing to, for
68 example, add cross-references. The QAPI Domain takes advantage of this
69 field list extension to document things like Arguments, Members, Values,
72 The special parsing and handling of info field lists in Sphinx is provided by
73 three main classes; Field, GroupedField, and TypedField. The behavior
74 and formatting for each configured field list entry in the domain
77 Field:
78   * Creates an ungrouped field: i.e., each entry will create its own
81   * May apply cross-reference roles to *either* the argument *or* the
89   * Creates a grouped field: i.e. multiple adjacent entries will be
92   * May optionally apply a cross-reference role to the argument, but not
96   * All items will be generated with the form: "argument -- body"
104   * Creates a grouped, typed field. Multiple adjacent entres will be
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 ----------
127 :availability: This field list is available in the body of Command,
139       Driver specific block device options for the virtio-blk-vhost-vdpa
142    :memb string path: path to the vhost-vdpa character device.
148 ---------
152 :availability: This field list is only available in the body of the
161    .. qapi:command:: job-pause
164       Pause an active job.
166       This command returns immediately after marking the active job for
179 -----------
183 :availability: This field list is only available in the body of the
186 :type: `sphinx.util.docfields.Field
187        <https://pydoc.dev/sphinx/latest/sphinx.util.docfields.Field.html?private=1>`_
189 The format of the :errors: field list description is free-form rST. The
195    .. qapi:command:: block-job-set-speed
200       This command can only be issued when there is an active block job.
210           - If no background operation is active on this device,
215 -------------
219 :availability: This field list is only available in the body of the
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 -----------
250 :availability: This field list is only available in the body of the Enum
266       :value DeviceNotActive: a device has failed to be become active
273 ------------
277 :availability: This field list is only available in the body of the
284 addition to the type, even though this information is not visible on the
302 ----------
306 :availability: This field list is available in the body of Event or
326 Arbitrary field lists
327 ---------------------
329 Other field list names, while valid rST syntax, are prohibited inside of
330 QAPI directives to help prevent accidental misspellings of info field
331 list names. If you want to add a new arbitrary "non-value-added" field
332 list to QAPI documentation, you must add the field name to the allow
341 Will allow you to add arbitrary field lists in QAPI directives::
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.
375 Type arguments in info field lists are converted into references as if
377 applies to both info field lists and standalone explicit
378 cross-references.
382 ----------------
385 ``[typename]``, to indicate an array of that type.  The cross-reference
390 To indicate an optional argument/member in a field list, the type name
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
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
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 --------------
530 -----------
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 ------------
556 ``:arg:``, ``:feat:``, ``:error:``, or ``:return:`` info field list
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 ----------
591 ``:memb:`` or ``:feat:`` info field list entries.
622 ---------
626 ``:value:`` or ``:feat:`` info field list entries.
635      :value Happy: Your VM is content and well-fed.
648    :value Happy: Your VM is content and well-fed.
655 -----------
659 documentation body may contain ``:memb:`` or ``:feat:`` info field list
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 --------------
693 ``:alt:`` or ``:feat:`` info field list entries.
702      :alt string em: An expletive-laced error message, if your
714    :alt string em: An expletive-laced error message, if your