motorhead/qemu
1
0
Fork 0
mirror of https://github.com/Motorhead1991/qemu.git synced 2025-07-27 04:13:53 -06:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs/qapidoc: add preamble() method

Browse source 
This method adds the options/preamble to each definition block. Notably,
:since: and :ifcond: are added, as are any "special features" such as
:deprecated: and :unstable:.

If conditionals, if attached to special features, are currently
unhandled in this patch and will be addressed at a future date. We
currently do not have any if conditionals attached to special features.

Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20250311034303.75779-44-jsnow@redhat.com>
Acked-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
This commit is contained in:
John Snow 2025-03-10 23:42:41 -04:00 • committed by Markus Armbruster
parent f0b2fe99f6
commit 803df114fd
1 changed files with 38 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

41
docs/sphinx/qapidoc.py
View file

@ -37,7 +37,12 @@ from docutils import nodes
from docutils.parsers.rst import Directive, directives
from docutils.statemachine import StringList
from qapi.error import QAPIError
from qapi.schema import QAPISchema, QAPISchemaVisitor
from qapi.parser import QAPIDoc
from qapi.schema import (
QAPISchema,
QAPISchemaDefinition,
QAPISchemaVisitor,
)
from qapi.source import QAPISourceInfo
from qapidoc_legacy import QAPISchemaGenRSTVisitor # type: ignore
@ -56,8 +61,6 @@ if TYPE_CHECKING:
Sequence,
)
from qapi.parser import QAPIDoc
from sphinx.application import Sphinx
from sphinx.util.typing import ExtensionMetadata
@ -125,6 +128,38 @@ class Transmogrifier:
# +2: correct for zero/one index, then increment by one.
self.add_line_raw("", fname, line + 2)
# Transmogrification helpers
def preamble(self, ent: QAPISchemaDefinition) -> None:
"""
Generate option lines for QAPI entity directives.
"""
if ent.doc and ent.doc.since:
assert ent.doc.since.kind == QAPIDoc.Kind.SINCE
# Generated from the entity's docblock; info location is exact.
self.add_line(f":since: {ent.doc.since.text}", ent.doc.since.info)
if ent.ifcond.is_present():
doc = ent.ifcond.docgen()
assert ent.info
# Generated from entity definition; info location is approximate.
self.add_line(f":ifcond: {doc}", ent.info)
# Hoist special features such as :deprecated: and :unstable:
# into the options block for the entity. If, in the future, new
# special features are added, qapi-domain will chirp about
# unrecognized options and fail until they are handled in
# qapi-domain.
for feat in ent.features:
if feat.is_special():
# FIXME: handle ifcond if present. How to display that
# information is TBD.
# Generated from entity def; info location is approximate.
assert feat.info
self.add_line(f":{feat.name}:", feat.info)
self.ensure_blank_line()
# Transmogrification core methods
def visit_module(self, path: str) -> None: