Re: [libvirt PATCH 2/2] meson: Detect and reject invalid rst2html5 command
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>
> ---
> 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(a)_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