configure: prefer sphinx-build to sphinx-build-3
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
@@ -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
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.
Signed-off-by John Snow <[email protected]>--- configure | 50 ++++++++++++++++++++++++++++++++------------------ 1 file changed, 32 insertions(+), 18 deletions(-)configure +32
-19@@ -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 --
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.
Signed-off-by John Snow <[email protected]>--- configure | 50 ++++++++++++++++++++++++++++++++------------------ 1 file changed, 32 insertions(+), 18 deletions(-)configure +32
-19@@ -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 --
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 :)
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
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
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
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_buildstep (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
516e8b7d4aand988ae6c3a7now in master.thanks
-- PMM
OK, Done.
--js