Re: [PATCH v3 5/6] meson: prefer 'sphinx-build' to 'sphinx-build-3'

[Paolo Bonzini <pbonzini@redhat.com>]

On 2/21/23 02:24, John Snow wrote:
> Once upon a time, "sphinx-build" on certain RPM platforms invoked
> specifically a Python 2.x version, while "sphinx-build-3" was a distro
> shim for the Python 3.x version.
> 
> These days, none of our supported platforms utilize a 2.x version, so it
> should be safe to search for 'sphinx-build' prior to 'sphinx-build-3',
> which will prefer pip/venv installed versions of sphinx if they're
> available.
> 
> This adds an extremely convenient ability to test document building
> ability in QEMU across multiple versions of Sphinx for the purposes of
> compatibility testing.

Can we just use "$PYTHON -m sphinx.cmd.build" instead, to ensure that we don't
escape the virtual environment?  Or even better, we could have a simple script
like this:

#! /usr/bin/env python3

from pkg_resources import load_entry_point

if __name__ == '__main__':
     if sys.argv[1] == '--check':
         try:
             load_entry_point(sys.argv[2], 'console_scripts', sys.argv[3])
             sys.exit(0)
         except ImportError:
             sys.exit(1)
     else:
         entry_point = load_entry_point(sys.argv[1], 'console_scripts', sys.argv[2])
         # The second argument to python-run.py becomes sys.argv[0]
         del sys.argv[0:1]
         sys.exit(entry_point())

then docs/meson.build can do this:

python_run = find_program('scripts/python-run.py')
build_docs = false
if get_feature('docs') \
   .require(run_command(python_run, '--check', 'sphinx', 'sphinx-build',
                        check: false).returncode() == 0,
            error: 'Could not find sphinx installation') \
   .allowed()
   # The sphinx module is installed
   SPHINX_ARGS = ['env', 'CONFDIR=' + qemu_confdir,
                  python_run, 'sphinx', 'sphinx-build', '-q']
   ...
   build_docs = (sphinx_build_test_out.returncode() == 0)
   ...
endif

This again ensures that sphinx-build will not escape the virtual environment
if there is one.  configure can also use the script to run meson, though that
can come later.

Paolo