Re: [PATCH v2 43/62] docs/qapidoc: add preamble() method

[John Snow <jsnow@redhat.com>]

[-- Attachment #1: Type: text/plain, Size: 3530 bytes --]

On Sun, Mar 9, 2025 at 5:03 PM Markus Armbruster <armbru@redhat.com> wrote:

> 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?
>

I don't know. isort decided to move it and none of my tooling complains
about it.


>
> >      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:
>
>

[-- Attachment #2: Type: text/html, Size: 5222 bytes --]