John Snow <js...@redhat.com> writes: > 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.
[...] > 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. Supporting such a wide range of versions is *expensive*. Writing compat.py is sunk cost. Maintaining it is not. It's fragile hacks, hard to understand even with deep Sphinx innards expertise, impossible to understand without. I figure if we somehow lost your expertise, we'd likely have to drop support for old Sphinx the moment compat.py breaks. Just because we can solve certain hard problems doesn't mean we should. I question the wisdom of supporting such a wide range of Sphinx versions.
