| Message ID | 20241213021827.2956769-12-jsnow@redhat.com (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | docs: add basic sphinx-domain rST generator to qapidoc | 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 | 33 ++++++++++++++++++++++++++++++++- > 1 file changed, 32 insertions(+), 1 deletion(-) > > diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py > index 6f8f69077b1..85c7ce94564 100644 > --- a/docs/sphinx/qapidoc.py > +++ b/docs/sphinx/qapidoc.py > @@ -38,7 +38,7 @@ > from qapi.error import QAPIError, QAPISemError > from qapi.gen import QAPISchemaVisitor > from qapi.parser import QAPIDoc > -from qapi.schema import QAPISchema > +from qapi.schema import QAPISchema, QAPISchemaEntity > from qapi.source import QAPISourceInfo > > from sphinx import addnodes > @@ -125,6 +125,37 @@ 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: QAPISchemaEntity) -> None: > + """ > + Generate option lines for qapi entity directives. > + """ > + if ent.doc and ent.doc.since: > + assert ent.doc.since.tag == QAPIDoc.Tag.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() > + # 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. > + for feat in ent.features: > + if feat.is_special(): > + # We don't expect special features to have an ifcond property. > + # (Hello, intrepid developer in the future who changed that!) > + # ((With luck, you are not me.)) > + assert not feat.ifcond.is_present() Nope :) The attempt to add a conditional special feature now fails with Sphinx parallel build error: AssertionError If you want to outlaw conditional special features, reject them cleanly in schema.py, document the restriction in docs/devel/qapi-code-gen.rst, and explain why in the commit message. Recommend a separate commit, to make it stand out in git-log. > + # Generated from entity def; info location is approximate. > + 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 6f8f69077b1..85c7ce94564 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -38,7 +38,7 @@ from qapi.error import QAPIError, QAPISemError from qapi.gen import QAPISchemaVisitor from qapi.parser import QAPIDoc -from qapi.schema import QAPISchema +from qapi.schema import QAPISchema, QAPISchemaEntity from qapi.source import QAPISourceInfo from sphinx import addnodes @@ -125,6 +125,37 @@ 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: QAPISchemaEntity) -> None: + """ + Generate option lines for qapi entity directives. + """ + if ent.doc and ent.doc.since: + assert ent.doc.since.tag == QAPIDoc.Tag.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() + # 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. + for feat in ent.features: + if feat.is_special(): + # We don't expect special features to have an ifcond property. + # (Hello, intrepid developer in the future who changed that!) + # ((With luck, you are not me.)) + assert not feat.ifcond.is_present() + # Generated from entity def; info location is approximate. + 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 | 33 ++++++++++++++++++++++++++++++++- 1 file changed, 32 insertions(+), 1 deletion(-)