Re: Bogus "is either too old or uses too old a Python version" from docs/meson.build

[Markus Armbruster]

Peter Maydell <peter.maydell@linaro.org> writes:

> On Thu, 25 Feb 2021 at 13:41, Markus Armbruster <armbru@redhat.com> wrote:
>> Peter Maydell <peter.maydell@linaro.org> writes:
>> > I'm not sure what could reasonably be done. The Sphinx test is just
>> > "try building a trivial document with our config (which is what
>> > enforces the version requirement)".
>>
>> This question is almost certainly naive: why is it necessary for the
>> "trivial" document to include the truckload generated by qapi-gen.py
>
> Because we want to use docs/conf.py, and docs/conf.py says
> "these are the plugins we use" (by setting the 'extensions' config
> variable, and so Sphinx will run the bit of the plugin that is "run this to
> initialize me".

I see.

> You could add conditionals to the conf.py to say "don't set the 'extensions'
> variable if we're being called for the trivial document by configure",
> but if there really is some problem with the user's environment that
> means that those extensions don't work, we'd rather have configure
> detect that and default to don't-build-docs, rather than configure
> believe that all is OK and then the 'make' later falling over.

Makes sense for the initial configure, but I'm afraid it's not what
happens in the "need to run config.status case" case.

If I configured with --enable-docs, then "make" running config.status
fails in the opaque way I described.  You argued anyone messing with the
QAPI generator should be capable of following the "A full log can be
found at" clue, and figure out what's wrong.  Fair enough, as long as we
ignore the possibility that qapi-gen could ever start to fail for
reasons other than "developer messed it up", such as "a Python upgrade
messed it up",

If I let configure decide whether to build docs, then "make" will fail
in the same clear way it always fails when the developer messes up
qapi-gen.  But first, it'll disable doc generation.  I'm pretty much
certain to miss that.  Fixing qapi-gen will *not* re-enable doc
generation.  It'll silently reenable itself the next time configure gets
run for some reason.  Until then, the build tree will contain stale
documentation.  I consider this a (relatively minor) trap for
developers.

Unrelated issue: touch any QAPI schema or QAPI generator source file,
rebuild the entire documentation.  This is a real drag.  The generated
code we only recompile when it changes.

I'm switching my primary build tree to --disable-docs now.  Less drag,
one less trap, and I rarely want to look at the formatted documentation
anyway.