[libvirt PATCH 2/2] meson: Detect and reject invalid rst2html5 command

[Andrea Bolognani]

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 at redhat.com>
> > ---
> >  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 at _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