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

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

[Markus Armbruster]

I just chanced on this one:

    Program sphinx-build-3 found: YES
    ../docs/meson.build:30: WARNING: /usr/bin/sphinx-build-3 is either too old or uses too old a Python version

    ../docs/meson.build:33:6: ERROR: Problem encountered: Install a Python 3 version of python-sphinx

    A full log can be found at /work/armbru/qemu/bld-x86/meson-logs/meson-log.txt

    ERROR: meson setup failed

My sphinx-build-3 is just fine, the problem is caused by me changing my
tree so that

1. qapi-gen.py fails (because I messed up), and

2. make re-runs configure.

Perhaps the test for a working sphinx-build-3 could be made a bit more
robust.

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

[Peter Maydell]

On Thu, 25 Feb 2021 at 12:23, Markus Armbruster <armbru@redhat.com> wrote:
>
> I just chanced on this one:
>
>     Program sphinx-build-3 found: YES
>     ../docs/meson.build:30: WARNING: /usr/bin/sphinx-build-3 is either too old or uses too old a Python version
>
>     ../docs/meson.build:33:6: ERROR: Problem encountered: Install a Python 3 version of python-sphinx
>
>     A full log can be found at /work/armbru/qemu/bld-x86/meson-logs/meson-log.txt
>
>     ERROR: meson setup failed
>
> My sphinx-build-3 is just fine, the problem is caused by me changing my
> tree so that
>
> 1. qapi-gen.py fails (because I messed up), and
>
> 2. make re-runs configure.
>
> Perhaps the test for a working sphinx-build-3 could be made a bit more
> robust.

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)". So yes, if you modify the QEMU sources
in a way that breaks the config file or one of the Sphinx plugins then
it'll trip the configure check. If you give the configure-check run
its own config file, then you end up with the version checks in two places
and they could get out of sync. One could try to have the conf.py have a
lot of conditionals to cut out things that the test-document doesn't use,
but then you run the risk that we no longer catch something for end-users
that we didn't anticipate that means we can't build the docs.

It seems more reasonable to me to assume that developers who are
actively modifying the QEMU code which is used in docs building
are able to read the log file that the error message points them
at, and can figure out what really happened from the log.

thanks
-- PMM

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 12:23, Markus Armbruster <armbru@redhat.com> wrote:
>>
>> I just chanced on this one:
>>
>>     Program sphinx-build-3 found: YES
>>     ../docs/meson.build:30: WARNING: /usr/bin/sphinx-build-3 is either too old or uses too old a Python version
>>
>>     ../docs/meson.build:33:6: ERROR: Problem encountered: Install a Python 3 version of python-sphinx
>>
>>     A full log can be found at /work/armbru/qemu/bld-x86/meson-logs/meson-log.txt
>>
>>     ERROR: meson setup failed
>>
>> My sphinx-build-3 is just fine, the problem is caused by me changing my
>> tree so that
>>
>> 1. qapi-gen.py fails (because I messed up), and
>>
>> 2. make re-runs configure.
>>
>> Perhaps the test for a working sphinx-build-3 could be made a bit more
>> robust.
>
> 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

>                                     So yes, if you modify the QEMU sources
> in a way that breaks the config file or one of the Sphinx plugins then
> it'll trip the configure check. If you give the configure-check run
> its own config file, then you end up with the version checks in two places
> and they could get out of sync. One could try to have the conf.py have a
> lot of conditionals to cut out things that the test-document doesn't use,
> but then you run the risk that we no longer catch something for end-users
> that we didn't anticipate that means we can't build the docs.
>
> It seems more reasonable to me to assume that developers who are
> actively modifying the QEMU code which is used in docs building
> are able to read the log file that the error message points them
> at, and can figure out what really happened from the log.

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

[Peter Maydell]

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

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.

-- PMM

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.