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 <js...@redhat.com>
---
docs/qapi/index.rst | 6 ++++++
docs/sphinx/qapi-domain.py | 11 ++++++++++-
2 files changed, 16 insertions(+), 1 deletion(-)
diff --git a/docs/qapi/index.rst b/docs/qapi/index.rst
index 197587bbc81..a570c37abb2 100644
--- a/docs/qapi/index.rst
+++ b/docs/qapi/index.rst
@@ -95,9 +95,15 @@ Explicit cross-referencing syntax for QAPI modules is
available with
:arg int foo: normal parameter documentation.
:arg str bar: Another normal parameter description.
:arg baz: Missing a type.
+ :feat unstable: More than unstable, this command doesn't even exist!
:arg no-descr:
+ :feat hallucination: This command is a figment of your imagination.
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.
+
+ At the moment, the order of grouped sections is based on the order in
+ which each group was encountered. This example will render Arguments
+ first, and then Features; but the order can be any that you choose.
diff --git a/docs/sphinx/qapi-domain.py b/docs/sphinx/qapi-domain.py
index 853bd91b7a8..c0dc6482204 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.docutils import SphinxDirective, switch_source_input
from sphinx.util.nodes import (
make_id,
@@ -146,6 +146,15 @@ class QAPIObject(ObjectDescription[Signature]):
}
)
+ doc_field_types = [
+ GroupedField(
+ "feature",
+ label=_("Features"),
+ names=("feat",),
+ can_collapse=True,
+ ),
+ ]
+
def get_signature_prefix(self, sig: str) -> List[nodes.Node]:
"""Returns a prefix to put before the object name in the signature."""
assert self.objtype
--
2.44.0
