Re: [PATCH 00/23] docs: add basic sphinx-domain rST generator to qapidoc

[Markus Armbruster]

John Snow <jsnow@redhat.com> writes:

> On Thu, Dec 19, 2024 at 7:31 AM Markus Armbruster <armbru@redhat.com> wrote:
>
>> John Snow <jsnow@redhat.com> writes:
>>
>> > based-on:
>> https://patchew.org/QEMU/20241213011307.2942030-1-jsnow@redhat.com/
>> >
>> > Hi!
>> >
>> > This series is a very, very barebones implementation for the new QAPI
>> > doc generator. It does not have many features that I presented on at KVM
>> > Forum; the point of this patch set is instead to present a stripped down
>> > basis for ongoing work so we can discuss on-list with full context of
>> > the code available to do so.
>> >
>> > The documentation this series generates is *not suitable* for replacing
>> > the current document generator, it has a few glaring omissions - on
>> > purpose - those features have been factored out intentionally so they
>> > can be reviewed with fuller context and more careful review.
>> >
>> > What this series does:
>> >
>> > - Adds the new "Transmogrifier" rST generator to qapidoc.py, which
>> >   generates an in-memory rST document using qapi-domain directives.
>> > - Adds a test document that showcases this new transmogrifier.
>>
>> Note to other reviewers: transmogrifier output is
>> docs/manual/qapi/index.html.
>>
>> > What this series very notably does not do (yet):
>> >
>> > - "ifcond" data for anything other than top-level entities is not
>> >   considered or rendered. This means "if" statements for features and
>> >   members are entirely absent.
>> >
>> > - The inliner is not present at all. This series renders only
>> >   documentation exactly as it is exists in the source files.
>>
>> This item is not even a regression.
>>
>
> No; but the version of this series as sent also does not add "The members
> of ..." stubs, which would be a regression.

Right.

>                                             I didn't necessarily intend for
> this to be merged as-is; more of a "part one, with additional tricky
> elements that require more careful thought isolated into separate patches
> for later".
>
> where "later" means "in v2" or "as a follow-up series as we stage things in
> a development branch before final submission for inclusion to
> origin/master" or whatever the actual mechanism is. I don't have a strong
> vision there, really; I just wanted to nail down the basics out in the open
> even if that was just between you (Markus) and I and we have a gentleman's
> agreement that it looks tentatively OK.

Got it.

>> > - *branches* are themselves not considered at all; they're skipped
>> >    entirely for now. They will be included alongside the inliner in
>> >    either a subsequent series or a followup to this series.
>> >
>> > - Undocumented members and return statements are not autogenerated.
>>
>> The current doc generator auto-generates missing member documentation
>> ("Not documented").  It doesn't auto-generate missing returns
>> documentation.  I explored auto-generating them, but shelved my work to
>> not interfere with yours.
>>
>> > - Pseudofeatures (Things like allow-oob) are not generated as documented
>> >   features.
>>
>> What exactly are "pseudofeatures"?
>>
>
> What I've named things like allow-oob that aren't features, but ought to be
> documented. We may well decide to promote them to real-deal special
> features, or maybe not. My work-in-progress branch currently just adds
> "dummy" features to document them. We can discuss this later alongside the
> patch that implements this.

I agree this is a digression, so feel free to ignore the remainder of my
reply for now.

We have two kinds of flags in the QAPI schema language: features and ad
hoc flags.  The ad hoc flags are 'boxed' (commands and events), 'gen',
'success-response', 'allow-oob', 'allow-preconfig', 'coroutine'
(commands only).

The flags sort into three buckets:

1. Code generation directives that do not affect the external interface,
and thus should not be visible in introspection: 'boxed', 'gen',
'coroutine'.

2. Flags that are visible at the external interface, but don't affect
code generation beyond making them visible in introspection: the
non-special features.

3. Code generation directives that affect the external interface, and
thus are (or should be) visible in introspection.

3a. The special features: are visible.

3b. 'allow-oob': is visible, but differently, because it predates
special features.

3c. 'allow-preconfig': not visible.

3d. 'success-response': not visible, because we use it for QGA only,
which doesn't provide introspection.

Bucket 3 could use cleanup.

[...]