[PATCH 1/1] configure: prefer python's sphinx module

[John Snow]

Using an explicit entry path script for sphinx can lead to confusing
results: If the python binary belongs to a virtual environment, our
configure script may still select a sphinx script that belongs to the
system distribution packages.

It is likely best to use python itself (whichever one the user provides)
to resolve the sphinx script. This has a few benefits:

1. It will always be Python 3. Script entry points like 'sphinx-build'
might attempt to invoke python2 -- or indeed, any version of python that
the user did not specify with --python.

2. When using a user installation of sphinx, it will naturally prefer
that version.

3. When using a virtual environment, it will naturally prefer that
version.

4. Removing explicit python script entry points gives us greater control
within the QEMU build ecosystem; we can be confident we are respecting
the user's --python configuration, if any.

It's my hope that this will make it simpler to integrate some optional
pipenv functionality into the build for adding regression testing to our
python module -- by offloading more of the python environment
configuration and testing directly to the python tooling ecosystem.

This would, ideally, free us up to use more modern python packages not
always offered in older system distributions. (For instance, we already
violate this requirement with sphinx, which does not have the necessary
versions in our oldest build platforms.)

Signed-off-by: John Snow <jsnow at redhat.com>
---
 docs/system/deprecated.rst | 19 +++++++++++++++++++
 configure                  | 20 +++++++++-----------
 2 files changed, 28 insertions(+), 11 deletions(-)

diff --git a/docs/system/deprecated.rst b/docs/system/deprecated.rst
index 544ece0a45e..a762a8c8043 100644
--- a/docs/system/deprecated.rst
+++ b/docs/system/deprecated.rst
@@ -17,6 +17,25 @@ they were first deprecated in the 2.10.0 release.
 What follows is a list of all features currently marked as
 deprecated.
 
+Configure script options
+------------------------
+
+``--sphinx-build=`` (since 5.1)
+'''''''''''''''''''''''''''''''
+
+The ``--sphinx-build`` option to select a specific sphinx-build entry
+point is replaced by configuring Python accordingly. QEMU will now
+default to using ``$python -m sphinx`` to use Python's preferred version
+of sphinx.
+
+Python will generally default to preferring user packages installed with
+``pip install --user`` first, and system distribution packages
+second. By specifying a custom Python binary or activating a virtual
+environment, Python will alter its module search behavior. As a last
+resort, the PYTHONPATH environment variable can be modified to specify
+an explicit directory.
+
+
 System emulator command line arguments
 --------------------------------------
 
diff --git a/configure b/configure
index b01b5e3bed0..e04b9d836ee 100755
--- a/configure
+++ b/configure
@@ -932,16 +932,6 @@ do
     fi
 done
 
-sphinx_build=
-for binary in sphinx-build-3 sphinx-build
-do
-    if has "$binary"
-    then
-        sphinx_build=$(command -v "$binary")
-        break
-    fi
-done
-
 # Check for ancillary tools used in testing
 genisoimage=
 for binary in genisoimage mkisofs
@@ -1014,7 +1004,9 @@ for opt do
   ;;
   --python=*) python="$optarg"
   ;;
-  --sphinx-build=*) sphinx_build="$optarg"
+  --sphinx-build=*)
+      sphinx_build="$optarg"
+      echo "--sphinx-build is deprecated. QEMU uses the specified python's sphinx module."
   ;;
   --gcov=*) gcov_tool="$optarg"
   ;;
@@ -4996,6 +4988,12 @@ has_sphinx_build() {
                     "$TMPDIR1/sphinx/out"  >> config.log 2>&1
 }
 
+# While we support --sphinx-build, defer to that.
+# Otherwise, use the module execution feature of Python.
+if ! has $sphinx_build; then
+    sphinx_build="$python -m sphinx"
+fi
+
 # Check if tools are available to build documentation.
 if test "$docs" != "no" ; then
   if has_sphinx_build; then
-- 
2.21.3