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 <jsnow@redhat.com>
---
 docs/sphinx/qapi_domain.py | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py
index 9919dacd4e6..64b540ff940 100644
--- a/docs/sphinx/qapi_domain.py
+++ b/docs/sphinx/qapi_domain.py
@@ -35,6 +35,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
 from sphinx.util.nodes import make_id, make_refnode
 
@@ -264,7 +265,18 @@ 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:-)
+    doc_field_types = QAPIObject.doc_field_types.copy()
+    doc_field_types.extend(
+        [
+            # :arg TypeName ArgName: descr
+            TypedField(
+                "argument",
+                label=_("Arguments"),
+                names=("arg",),
+                can_collapse=False,
+            ),
+        ]
+    )
 
 
 class QAPIModule(SphinxDirective):
-- 
2.48.1

John Snow <jsnow@redhat.com> writes:

> 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.

Exuse my nitpicking...  "cannot omit" suggests omission is a hard error.
The text after "--" suggests it isn't, it gives you something that
"probably isn't what you want".  Which way does it actually behave?

>
> Signed-off-by: John Snow <jsnow@redhat.com>

On Fri, Mar 7, 2025 at 2:46 AM Markus Armbruster <armbru@redhat.com> wrote:

> John Snow <jsnow@redhat.com> writes:
>
> > 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.
>
> Exuse my nitpicking...  "cannot omit" suggests omission is a hard error.
> The text after "--" suggests it isn't, it gives you something that
> "probably isn't what you want".  Which way does it actually behave?
>

Haha.

If you omit the name, the info field list entry degrades into a
rst-standard field list entry. Later in the series, I explicitly prohibit
that because it is definitely not what you want at all.

info field list = special processing is applied to group entries, labels
are added, add xrefs, etc
field list = regular definition list exactly as typed. I.e. the label will
be "arg:"


>
> >
> > Signed-off-by: John Snow <jsnow@redhat.com>
>
>