On Mon, Mar 10, 2025 at 5:05 PM John Snow <js...@redhat.com> wrote:
>
>
> On Sun, Mar 9, 2025 at 5:03 PM Markus Armbruster <arm...@redhat.com>
> wrote:
>
>> John Snow <js...@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 <js...@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.
>
Ah, no, it's because it becomes used at runtime. Promoted from "type hint
only".
--js
>
>
>>
>> > 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:
>>
>>
