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 -- Andrea Bolognani / Red Hat / Virtualization
