On Tue, Aug 10, 2021 at 05:02:54AM -0700, Andrea Bolognani wrote: > On Tue, Aug 10, 2021 at 11:05:42AM +0100, Daniel P. Berrangé wrote: > > On Mon, Aug 09, 2021 at 05:13:29PM +0200, Andrea Bolognani wrote: > > > The version coming from the rst2html5 package instead of the > > > docutils package is unable to successfully generate the libvirt > > > documentation. > > > > > > Examples of users encountering build issues because of the wrong > > > version of rst2html5 being installed on their systems: > > > > > > https://gitlab.com/libvirt/libvirt/-/issues/40 > > > https://gitlab.com/libvirt/libvirt/-/issues/139 > > > https://gitlab.com/libvirt/libvirt/-/issues/169 > > > https://gitlab.com/libvirt/libvirt/-/issues/195 > > > > > > Signed-off-by: Andrea Bolognani <abologna@xxxxxxxxxx> > > > --- > > > meson.build | 28 ++++++++++++++++++++++++++++ > > > 1 file changed, 28 insertions(+) > > > > > > diff --git a/meson.build b/meson.build > > > index 32ad688c9c..02357a2678 100644 > > > --- a/meson.build > > > +++ b/meson.build > > > @@ -813,6 +813,34 @@ foreach item : required_programs_groups > > > set_variable('@0@_prog'.format(varname), prog) > > > endforeach > > > > > > +# There are two versions of rst2html5 in the wild: one is the version > > > +# coming from the docutils package, and the other is the one coming > > > +# from the rst2html5 package. These versions are subtly different, > > > +# and the libvirt documentation can only be successfully generated > > > +# using the docutils version. Every now and then, users will report > > > +# build failures that can be traced back to having the wrong version > > > +# installed. > > > +# > > > +# The only reliable way to tell the two binaris apart seems to be > > > +# looking look at their version information: the docutils version > > > +# will report > > > +# > > > +# rst2html5 (Docutils ..., Python ..., on ...) > > > +# > > > +# whereas the rst2html5 version will report > > > +# > > > +# rst2html5 ... (Docutils ..., Python ..., on ...) > > > +# > > > +# with the additional bit of information being the version number for > > > +# the rst2html5 package itself. > > > > This feels way too fragile to me. > > > > Can't we just write out a 5 line rst doc showing the problem and > > try to run the command to detect brokeness ? > > Last time we discussed this, crafting a document that would trigger > one of the known differences in behavior was also deemed "kind of > fragile"[1]. > > Ultimately I don't think there's a way to tell the two binaries apart > which isn't at least a bit susceptible to breaking down the line, > especially because the rst2html5 package appears to be trying its > best to be a drop-in replacement - except of course for the things > that are different. > > That said, considering that the good rst2html5 binary comes from the > docutils package itself I don't really foresee a scenario where they > would have to introduce additional version information: it will > naturally be versioned the same as docutils itself. So this feels > like a reasonably future-proof detection method. > > Once again, I'm all hears when it comes to alternative ideas. AFAIK > nobody has manged to come up with something that we're all 100% happy > with, and I would hate to just leave things as they are because users > keep hitting the issue - which incidentally also means that > developers have to spend time debugging it and guiding them to the > solution every single time. > > > [1] https://listman.redhat.com/archives/libvir-list/2021-June/msg00196.html Resurrecting an old thread. Dan, should I consider your criticism of the approach an explicit NACK? If not, I will pick up Pavel's ACK and push this. I think the latter is the right thing to do, on the basis that it will leave us in a place that's strictly better than the status quo and that - to the best of my knowledge - no alternative that doesn't itself suffer from known drawbacks has been proposed. -- Andrea Bolognani / Red Hat / Virtualization
