| Message ID | 20250309083550.5155-44-jsnow@redhat.com (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | docs: Add new QAPI transmogrifier | expand |
John Snow <jsnow@redhat.com> writes: > 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:. > > Signed-off-by: John Snow <jsnow@redhat.com> > --- > docs/sphinx/qapidoc.py | 41 ++++++++++++++++++++++++++++++++++++++--- > 1 file changed, 38 insertions(+), 3 deletions(-) > > diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py > index cf5dbb0133d..d8bf0073dfa 100644 > --- a/docs/sphinx/qapidoc.py > +++ b/docs/sphinx/qapidoc.py > @@ -37,7 +37,12 @@ > 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 @@ > Sequence, > ) > > - from qapi.parser import QAPIDoc > - Accident? > from sphinx.application import Sphinx > from sphinx.util.typing import ExtensionMetadata > > @@ -125,6 +128,38 @@ def ensure_blank_line(self) -> None: > # +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) Break the line aftee the comma? > + > + 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 If I remember correctly, you wanted to mention this FIXME in the commit message. > + # 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:
diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index cf5dbb0133d..d8bf0073dfa 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -37,7 +37,12 @@ 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 @@ Sequence, ) - from qapi.parser import QAPIDoc - from sphinx.application import Sphinx from sphinx.util.typing import ExtensionMetadata @@ -125,6 +128,38 @@ def ensure_blank_line(self) -> None: # +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:
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:. Signed-off-by: John Snow <jsnow@redhat.com> --- docs/sphinx/qapidoc.py | 41 ++++++++++++++++++++++++++++++++++++++--- 1 file changed, 38 insertions(+), 3 deletions(-)