[v2,16/62] docs/qapi-domain: add "Features:" field lists

Commit Message

John Snow March 9, 2025, 8:35 a.m. UTC

Add support for Features field lists. There is no QAPI-specific
functionality here, but this could be changed if desired (if we wanted
the feature names to link somewhere, for instance.)

This feature list doesn't have any restrictions, so it can be used to
document object-wide features or per-member features as deemed
appropriate. It's essentially free-form text.

Signed-off-by: John Snow <[e-mail]>
---
 docs/sphinx/qapi_domain.py | 12 +++++++++++-
 1 file changed, 11 insertions(+), 1 deletion(-)

Comments

Markus Armbruster March 9, 2025, 8:42 p.m. UTC | #1

John Snow <[e-mail]> writes:

> Add support for Features field lists. There is no QAPI-specific
> functionality here, but this could be changed if desired (if we wanted
> the feature names to link somewhere, for instance.)
>
> This feature list doesn't have any restrictions, so it can be used to
> document object-wide features or per-member features as deemed
> appropriate. It's essentially free-form text.
>
> Signed-off-by: John Snow <[e-mail]>

Mention the new syntax :feat, like the previous patch does for :arg?

Patch

diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py
index c0a1a1f9ee8..21d487514ec 100644
--- a/docs/sphinx/qapi_domain.py
+++ b/docs/sphinx/qapi_domain.py
@@ -33,7 +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.docfields import GroupedField, TypedField
 from sphinx.util.nodes import make_id, make_refnode
 
 
@@ -184,6 +184,16 @@  class QAPIObject(QAPIDescription):
         }
     )
 
+    doc_field_types = [
+        # :feat name: descr
+        GroupedField(
+            "feature",
+            label=_("Features"),
+            names=("feat",),
+            can_collapse=False,
+        ),
+    ]
+
     def get_signature_prefix(self) -> List[nodes.Node]:
         """Returns a prefix to put before the object name in the signature."""
         assert self.objtype