On Wed, Mar 5, 2025, 6:31 AM Markus Armbruster <arm...@redhat.com> wrote:
> 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? > I hope so too, though some of the sphinx version compatibility hacks are possibly fairly porcelain. The most egregious of them are for versions prior to Sphinx 4.1. Almost all of the compatibility hacks are factored into compat.py and they are all documented with what versions they're there for. Most of the ugliest is pre-4.1. > > > > 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 ;) > Missing documentation for undocumented members. You found one! :) > > 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. > It's the stuff in compat.py that was the absolute hardest. You need that stuff for this to work on the version ranges it works for, but typing it was an extra special torture. >
