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(a)redhat.com&gt; --- 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(&#39;@0(a)_prog&#39;.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.

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(a)redhat.com&gt; > > --- > > 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(&#39;@0(a)_prog&#39;.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