Re: [PATCH 00/57] docs: Add new QAPI transmogrifier

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@redhat.com> writes:

> Hi! This series is based on armbru/pull-qapi-2025-02-26.
>
> This series is a "minimum viable" version of the new QAPI documentation
> system. It does the bare minimum under the new framework, saving nice
> features for later.

Not saved for later: a massive improvement of the generated
documentation's looks and usability.  Moreover, I hope the new generator
will be easier to maintain than the old one, because its inner workings
are closer to how Sphinx expects such things to work.  Fair?

>
> Patches 3-29 implement the qapi_domain extension.
> Patches 30-57 implement the qapidoc "Transmogrifier".
>
> This series is still "RFC" quality, though it's quite nearly actually
> ready for inclusion. The "add transmogrifier test document" patch is not
> intended for actual merge, it's just there to demonstrate the new
> document generator by producing output in docs/manual/qapi/index.html.
>
> Known shortcomings in this series:
>
> - Still no new QAPI unit tests. I'll add those for next go-around.

Not a blocker as far as I'm concerned, because I feel you're unlikely to
run away from this :)

> - No new documentation. Also for next revision. I'll document the QAPI
>   domain syntax and give a brief overview of how the transmogrifier
>   functions, and a quick rundown of any new rST syntax that may be
>   pertinent to QAPI documentation writers.

Likewise.

> - IFCOND information is still rendered in two places, we'll need to
>   decide where and how we want to render it.

I'll have a look, and then we'll talk.

> - No QAPI namespace support ... yet. So we can't enable it for QMP, QGA
>   and QSD simultaneously just yet. I don't think it will be difficult.
>
> Unknown shortcomings in this series:
>
> - ???

I'll try to find some, but I'm not overly optimistic ;)

> New stuff overall from the last iteration of this series:
>
> - @foo is processed into ``foo`
> - "The members of ..." messages have been temporarily re-added until we
>   can smooth over the inliner.
> - This series runs under Sphinx 3.4.3 to Sphinx 8.2.0 inclusive. It
>   truly is a Christmas miracle. (please clap)

*clap* clap* clap*

This is waaaay harder than it has any right to be.

> - This series now fully type checks and lint checks under Sphinx 8.2.0,
>   but may not type check under earlier Sphinx versions. Achieving this
>   alone, nevermind in conjunction with the above, was a literal
>   herculean labor.

scripts/qapi/ remains clean for me.  docs/sphinx/ improves from no type
checking to type checking with a version newer than the one I have on my
development box right now, which I count as an improvement.

> I really must stress again how frustratingly difficult it was to achieve
> the prior two bullet points. I *do* in fact want a cookie and/or an
> award ribbon.

We owe you an entire layer cake, with a marzipan figurine of your
conquering self on top.  Seriously, I could not have done this.