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

[Andrea Bolognani]

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 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

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