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>`_
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,
74 and formatting for each configured field list entry in the domain
81   * May apply cross-reference roles to *either* the argument *or* the
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
94   * Can be configured to remove the bulleted list if there is only a
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
110   * Can be configured to remove the bulleted list if there is only a
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
179 -----------
183 :availability: This field list is only available in the body of the
189 The format of the :errors: field list description is free-form rST. The
195    .. qapi:command:: block-job-set-speed
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
273 ------------
277 :availability: This field list is only available in the body of the
302 ----------
306 :availability: This field list is available in the body of Event or
327 ---------------------
329 Other field list names, while valid rST syntax, are prohibited inside of
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
333 list in ``docs/conf.py``
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
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 ----------
400 Mimicking the `Python domain target specification syntax
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`
415 Target resolution
416 -----------------
418 Any cross-reference to a QAPI type, whether using the ```any``` style of
419 reference or the more explicit ```:qapi:any:`target``` syntax, allows
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>`_
443 using the ``custom text <target>`` 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