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
Yeah, I proposed we use "python3 -m sphinx.cmd.build" once, but Peter did not like the idea of Sphinx becoming a python dependency instead of being treated as a black box.
Obviously circumstances are shifting somewhat and we may be more open to treating Sphinx as a python dependency given that we need to enforce compatibility with custom plugins written in qemu.git.
If I was trying to please absolutely nobody but me, I'd certainly use the `$python -m sphinx` approach; especially because it means that for qapi-gen, the code is run under the same environment in both cases (native qapi-gen exec and sphinx doc building).
I'm for it, but lost appetite for making the argument some time back.