On Tue, Feb 21, 2023, 6:31 AM Paolo Bonzini <pbonz...@redhat.com> wrote:
> 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.
>
