John Snow <js...@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.
