This adds special rendering for Sphinx's typed field lists.
This patch does not add any QAPI-aware markup, rendering, or
cross-referencing for the type names, yet. That feature requires a
subclass to TypedField which will happen in its own commit quite a bit
later in this series; after all the basic fields and objects have been
established first.
The syntax for this field is:
:arg type name: description
description cont'd
You can omit the type or the description, but you cannot omit the name
-- if you do so, it degenerates into a "normal field list" entry, and
probably isn't what you want.
Signed-off-by: John Snow <js...@redhat.com>
---
docs/qapi/index.rst | 15 +++++++++++++++
docs/sphinx/qapi-domain.py | 14 ++++++++++++--
2 files changed, 27 insertions(+), 2 deletions(-)
diff --git a/docs/qapi/index.rst b/docs/qapi/index.rst
index 33b9349a3ee..197587bbc81 100644
--- a/docs/qapi/index.rst
+++ b/docs/qapi/index.rst
@@ -86,3 +86,18 @@ Explicit cross-referencing syntax for QAPI modules is
available with
* ``:no-index-entry:`` or ``:noindexentry:``
* ``:no-contents-entry:`` or ``:nocontentsentry:``
* ``:no-typesetting:``
+
+.. qapi:command:: fake-command
+ :since: 13.37
+
+ This is a fake command, it's not real. It can't hurt you.
+
+ :arg int foo: normal parameter documentation.
+ :arg str bar: Another normal parameter description.
+ :arg baz: Missing a type.
+ :arg no-descr:
+
+ Field lists can appear anywhere in the directive block, but any field
+ list entries in the same list block that are recognized as special
+ ("arg") will be reformatted and grouped accordingly for rendered
+ output.
diff --git a/docs/sphinx/qapi-domain.py b/docs/sphinx/qapi-domain.py
index 38a50318d08..853bd91b7a8 100644
--- a/docs/sphinx/qapi-domain.py
+++ b/docs/sphinx/qapi-domain.py
@@ -33,6 +33,7 @@
from sphinx.locale import _, __
from sphinx.roles import XRefRole
from sphinx.util import logging
+from sphinx.util.docfields import TypedField
from sphinx.util.docutils import SphinxDirective, switch_source_input
from sphinx.util.nodes import (
make_id,
@@ -254,8 +255,17 @@ def _toc_entry_name(self, sig_node: desc_signature) -> str:
class QAPICommand(QAPIObject):
"""Description of a QAPI Command."""
- # Nothing unique for now! Changed in later commits O:-)
- pass
+ doc_field_types = QAPIObject.doc_field_types.copy()
+ doc_field_types.extend(
+ [
+ TypedField(
+ "argument",
+ label=_("Arguments"),
+ names=("arg",),
+ can_collapse=True,
+ ),
+ ]
+ )
class QAPIModule(SphinxDirective):
--
2.44.0
