| Message ID | 20250309083550.5155-16-jsnow@redhat.com (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | docs: Add new QAPI transmogrifier | expand |
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. Suggest "You can omit the type or the description. You should not omit the name ..." > > Signed-off-by: John Snow <jsnow@redhat.com>
diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index 51a15714bf0..c0a1a1f9ee8 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.nodes import make_id, make_refnode @@ -268,7 +269,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(QAPIDescription):
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(-)