Skip to contentSkip to conversation

configure: prefer sphinx-build to sphinx-build-3

RFC PATCH Superseded John Snow 4 participants 8 messages Apr 15, 2020 – May 13, 2020

v1 of 2 Superseded Latest is v2 →

lore
Share & tools
lore

John Snow

author
#0 lore raw

RFC PATCH 1/1 configure: prefer sphinx-build to sphinx-build-3

sphinx-build is the name of the script entry point from the sphinx package itself. sphinx-build-3 is a pacakging convention by Linux distributions. Prefer, where possible, the canonical package name.

In the event that this resolves to a python2 version, test the suitability of the binary early in the configuration process, and continue looking for sphinx-build-3 if necessary.

This prioritizes a virtual environment version of sphinx above any distribution versions, if attempting to build of a virtual python environment.

---
 configure | 50 ++++++++++++++++++++++++++++++++------------------
 1 file changed, 32 insertions(+), 18 deletions(-)
configure +32 -18
index 233c671aaa..82143e8a41 100755
@@ -928,13 +928,34 @@ do
     fi
 done
 
+# Check we have a new enough version of sphinx-build
+test_sphinx_build() {
+    sphinx=$1
+    # This is a bit awkward but works: create a trivial document and
+    # try to run it with our configuration file (which enforces a
+    # version requirement). This will fail if either
+    # sphinx-build doesn't exist at all or if it is too old.
+    mkdir -p "$TMPDIR1/sphinx"
+    touch "$TMPDIR1/sphinx/index.rst"
+    "$sphinx" -c "$source_path/docs" -b html "$TMPDIR1/sphinx" "$TMPDIR1/sphinx/out" >/dev/null 2>&1
+}
+
+# We require the python3 version of sphinx, but sphinx-build-3 is a
+# distro package. prefer 'sphinx-build' to find the venv version, if
+# any, but ensure it is a suitable version.
 sphinx_build=
-for binary in sphinx-build-3 sphinx-build
+sphinx_ok=
+for binary in sphinx-build sphinx-build-3
 do
     if has "$binary"
     then
-        sphinx_build=$(command -v "$binary")
-        break
+        sphinx_candidate=$(command -v "$binary")
+        if test_sphinx_build "$sphinx_candidate"
+        then
+            sphinx_build=$sphinx_candidate
+            sphinx_ok=yes
+            break
+        fi
     fi
 done
 
@@ -4928,24 +4949,17 @@ if check_include sys/kcov.h ; then
     kcov=yes
 fi
 
-# Check we have a new enough version of sphinx-build
-has_sphinx_build() {
-    # This is a bit awkward but works: create a trivial document and
-    # try to run it with our configuration file (which enforces a
-    # version requirement). This will fail if either
-    # sphinx-build doesn't exist at all or if it is too old.
-    mkdir -p "$TMPDIR1/sphinx"
-    touch "$TMPDIR1/sphinx/index.rst"
-    "$sphinx_build" -c "$source_path/docs" -b html "$TMPDIR1/sphinx" "$TMPDIR1/sphinx/out" >/dev/null 2>&1
-}
-
 # Check if tools are available to build documentation.
 if test "$docs" != "no" ; then
-  if has_sphinx_build; then
-    sphinx_ok=yes
-  else
-    sphinx_ok=no
+
+  if [ "$sphinx_ok" != "yes" ]; then
+    if test_sphinx_build "$sphinx_build"; then
+      sphinx_ok=yes
+    else
+      sphinx_ok=no
+    fi
   fi
+
   if has makeinfo && has pod2man && test "$sphinx_ok" = "yes"; then
     docs=yes
   else
Signature · 1 line
2.21.1
#1 lore raw
Quoted 4 lines · John Snow

sphinx-build is the name of the script entry point from the sphinx package itself. sphinx-build-3 is a pacakging convention by Linux distributions. Prefer, where possible, the canonical package name.

This was Markus's code originally; cc'ing him.

(Incidentally I think when we say "Linux distributions" we really mean "Red Hat"; Debian/Ubuntu don't use the "sphinx-build-3" name.)

thanks
-- PMM
(rest of email untrimmed for context)

Quoted 89 lines

In the event that this resolves to a python2 version, test the suitability of the binary early in the configuration process, and continue looking for sphinx-build-3 if necessary.

This prioritizes a virtual environment version of sphinx above any distribution versions, if attempting to build of a virtual python environment.

---
 configure | 50 ++++++++++++++++++++++++++++++++------------------
 1 file changed, 32 insertions(+), 18 deletions(-)
configure +32 -19
index 233c671aaa..82143e8a41 100755
@@ -928,13 +928,34 @@ do
     fi
 done
 
+# Check we have a new enough version of sphinx-build
+test_sphinx_build() {
+    sphinx=$1
+    # This is a bit awkward but works: create a trivial document and
+    # try to run it with our configuration file (which enforces a
+    # version requirement). This will fail if either
+    # sphinx-build doesn't exist at all or if it is too old.
+    mkdir -p "$TMPDIR1/sphinx"
+    touch "$TMPDIR1/sphinx/index.rst"
+    "$sphinx" -c "$source_path/docs" -b html "$TMPDIR1/sphinx" "$TMPDIR1/sphinx/out" >/dev/null 2>&1
+}
+
+# We require the python3 version of sphinx, but sphinx-build-3 is a
+# distro package. prefer 'sphinx-build' to find the venv version, if
+# any, but ensure it is a suitable version.
 sphinx_build=
-for binary in sphinx-build-3 sphinx-build
+sphinx_ok=
+for binary in sphinx-build sphinx-build-3
 do
     if has "$binary"
     then
-        sphinx_build=$(command -v "$binary")
-        break
+        sphinx_candidate=$(command -v "$binary")
+        if test_sphinx_build "$sphinx_candidate"
+        then
+            sphinx_build=$sphinx_candidate
+            sphinx_ok=yes
+            break
+        fi
     fi
 done
 
@@ -4928,24 +4949,17 @@ if check_include sys/kcov.h ; then
     kcov=yes
 fi
 
-# Check we have a new enough version of sphinx-build
-has_sphinx_build() {
-    # This is a bit awkward but works: create a trivial document and
-    # try to run it with our configuration file (which enforces a
-    # version requirement). This will fail if either
-    # sphinx-build doesn't exist at all or if it is too old.
-    mkdir -p "$TMPDIR1/sphinx"
-    touch "$TMPDIR1/sphinx/index.rst"
-    "$sphinx_build" -c "$source_path/docs" -b html "$TMPDIR1/sphinx" "$TMPDIR1/sphinx/out" >/dev/null 2>&1
-}
-
 # Check if tools are available to build documentation.
 if test "$docs" != "no" ; then
-  if has_sphinx_build; then
-    sphinx_ok=yes
-  else
-    sphinx_ok=no
+
+  if [ "$sphinx_ok" != "yes" ]; then
+    if test_sphinx_build "$sphinx_build"; then
+      sphinx_ok=yes
+    else
+      sphinx_ok=no
+    fi
   fi
+
   if has makeinfo && has pod2man && test "$sphinx_ok" = "yes"; then
     docs=yes
   else
--
author
#2 lore raw
Quoted 11 lines · Peter Maydell
Quoted 4 lines · John Snow

sphinx-build is the name of the script entry point from the sphinx package itself. sphinx-build-3 is a pacakging convention by Linux distributions. Prefer, where possible, the canonical package name.

This was Markus's code originally; cc'ing him.

(Incidentally I think when we say "Linux distributions" we really mean "Red Hat"; Debian/Ubuntu don't use the "sphinx-build-3" name.)

I'll take your word for it :)

Quoted 4 lines

thanks
-- PMM
(rest of email untrimmed for context)

My only goal here is that if you are using a virtual environment with sphinx installed that it prefers that, so non-standard names need to come last.

There's probably 10,000,000 ways to do that, hence the RFC.

--js

Quoted 90 lines
Quoted 89 lines

In the event that this resolves to a python2 version, test the suitability of the binary early in the configuration process, and continue looking for sphinx-build-3 if necessary.

This prioritizes a virtual environment version of sphinx above any distribution versions, if attempting to build of a virtual python environment.

---
 configure | 50 ++++++++++++++++++++++++++++++++------------------
 1 file changed, 32 insertions(+), 18 deletions(-)
configure +32 -19
index 233c671aaa..82143e8a41 100755
@@ -928,13 +928,34 @@ do
     fi
 done
 
+# Check we have a new enough version of sphinx-build
+test_sphinx_build() {
+    sphinx=$1
+    # This is a bit awkward but works: create a trivial document and
+    # try to run it with our configuration file (which enforces a
+    # version requirement). This will fail if either
+    # sphinx-build doesn't exist at all or if it is too old.
+    mkdir -p "$TMPDIR1/sphinx"
+    touch "$TMPDIR1/sphinx/index.rst"
+    "$sphinx" -c "$source_path/docs" -b html "$TMPDIR1/sphinx" "$TMPDIR1/sphinx/out" >/dev/null 2>&1
+}
+
+# We require the python3 version of sphinx, but sphinx-build-3 is a
+# distro package. prefer 'sphinx-build' to find the venv version, if
+# any, but ensure it is a suitable version.
 sphinx_build=
-for binary in sphinx-build-3 sphinx-build
+sphinx_ok=
+for binary in sphinx-build sphinx-build-3
 do
     if has "$binary"
     then
-        sphinx_build=$(command -v "$binary")
-        break
+        sphinx_candidate=$(command -v "$binary")
+        if test_sphinx_build "$sphinx_candidate"
+        then
+            sphinx_build=$sphinx_candidate
+            sphinx_ok=yes
+            break
+        fi
     fi
 done
 
@@ -4928,24 +4949,17 @@ if check_include sys/kcov.h ; then
     kcov=yes
 fi
 
-# Check we have a new enough version of sphinx-build
-has_sphinx_build() {
-    # This is a bit awkward but works: create a trivial document and
-    # try to run it with our configuration file (which enforces a
-    # version requirement). This will fail if either
-    # sphinx-build doesn't exist at all or if it is too old.
-    mkdir -p "$TMPDIR1/sphinx"
-    touch "$TMPDIR1/sphinx/index.rst"
-    "$sphinx_build" -c "$source_path/docs" -b html "$TMPDIR1/sphinx" "$TMPDIR1/sphinx/out" >/dev/null 2>&1
-}
-
 # Check if tools are available to build documentation.
 if test "$docs" != "no" ; then
-  if has_sphinx_build; then
-    sphinx_ok=yes
-  else
-    sphinx_ok=no
+
+  if [ "$sphinx_ok" != "yes" ]; then
+    if test_sphinx_build "$sphinx_build"; then
+      sphinx_ok=yes
+    else
+      sphinx_ok=no
+    fi
   fi
+
   if has makeinfo && has pod2man && test "$sphinx_ok" = "yes"; then
     docs=yes
   else
--
#3 lore raw
Quoted 20 lines · John Snow
Quoted 11 lines · Peter Maydell
Quoted 4 lines · John Snow

sphinx-build is the name of the script entry point from the sphinx package itself. sphinx-build-3 is a pacakging convention by Linux distributions. Prefer, where possible, the canonical package name.

This was Markus's code originally; cc'ing him.

(Incidentally I think when we say "Linux distributions" we really mean "Red Hat"; Debian/Ubuntu don't use the "sphinx-build-3" name.)

I'll take your word for it :)

Quoted 4 lines

thanks
-- PMM
(rest of email untrimmed for context)

Quoted 5 lines

My only goal here is that if you are using a virtual environment with sphinx installed that it prefers that, so non-standard names need to come last.

There's probably 10,000,000 ways to do that, hence the RFC.

My goal when I wrote the patch was to make the doc-building work out of the box on systems where sphinx-build gets you a Python 2 Sphinx, which does not work for us, and sphinx-build-3 gets you one that does.

I patterned the Sphinx check after the Python check: first the -3. and only then the indeterminate version.

I won't object to a patch that makes things better for you without making them worse for me :)

#4 lore raw
In reply to John Snow
Quoted 20 lines · John Snow
Quoted 11 lines · Peter Maydell
Quoted 4 lines · John Snow

sphinx-build is the name of the script entry point from the sphinx package itself. sphinx-build-3 is a pacakging convention by Linux distributions. Prefer, where possible, the canonical package name.

This was Markus's code originally; cc'ing him.

(Incidentally I think when we say "Linux distributions" we really mean "Red Hat"; Debian/Ubuntu don't use the "sphinx-build-3" name.)

I'll take your word for it :)

Quoted 4 lines

thanks
-- PMM
(rest of email untrimmed for context)

Quoted 5 lines

My only goal here is that if you are using a virtual environment with sphinx installed that it prefers that, so non-standard names need to come last.

There's probably 10,000,000 ways to do that, hence the RFC.

What's wrong with just passing --sphinx-build=sphinx-build in your configure string? It will override whatever we auto-detect AFAICT.

Signature · 1 line
Alex Bennée
author
#5 lore raw
Quoted 23 lines · Alex Bennée
Quoted 20 lines · John Snow
Quoted 11 lines · Peter Maydell
Quoted 4 lines · John Snow

sphinx-build is the name of the script entry point from the sphinx package itself. sphinx-build-3 is a pacakging convention by Linux distributions. Prefer, where possible, the canonical package name.

This was Markus's code originally; cc'ing him.

(Incidentally I think when we say "Linux distributions" we really mean "Red Hat"; Debian/Ubuntu don't use the "sphinx-build-3" name.)

I'll take your word for it :)

Quoted 4 lines

thanks
-- PMM
(rest of email untrimmed for context)

Quoted 9 lines
Quoted 5 lines

My only goal here is that if you are using a virtual environment with sphinx installed that it prefers that, so non-standard names need to come last.

There's probably 10,000,000 ways to do that, hence the RFC.

What's wrong with just passing --sphinx-build=sphinx-build in your configure string? It will override whatever we auto-detect AFAICT.

My goal is to make virtual environments work out of the box.

I.e., if you run ./configure from inside a VENV, it should "just work."

--js

#6 lore raw
Quoted 3 lines · John Snow

My goal is to make virtual environments work out of the box.

I.e., if you run ./configure from inside a VENV, it should "just work."

Yeah, this seems reasonable to me. If I understand your patch correctly it ought to work without breaking the setup Markus describes, because in that case 'sphinx-build' exists but will fail the test_sphinx_build step (because it's a Python 2 sphinx-build) and we'll then move on and use sphinx-build-3.

Patch looks good to me, but you'll need to rebase and update it to take account of commits 516e8b7d4a and 988ae6c3a7 now in master.

thanks
-- PMM

author
#7 lore raw
Quoted 12 lines · Peter Maydell
Quoted 3 lines · John Snow

My goal is to make virtual environments work out of the box.

I.e., if you run ./configure from inside a VENV, it should "just work."

Yeah, this seems reasonable to me. If I understand your patch correctly it ought to work without breaking the setup Markus describes, because in that case 'sphinx-build' exists but will fail the test_sphinx_build step (because it's a Python 2 sphinx-build) and we'll then move on and use sphinx-build-3.

Quoted 7 lines

Patch looks good to me, but you'll need to rebase and update it to take account of commits 516e8b7d4a and 988ae6c3a7 now in master.

thanks
-- PMM

OK, Done.

--js