Re: [PATCH RFC] configure: prefer sphinx-build to sphinx-build-3

[Peter Maydell <peter.maydell@linaro.org>]

On Wed, 15 Apr 2020 at 18:33, John Snow <jsnow@redhat.com> wrote:
>
> 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)

> 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 <jsnow@redhat.com>
> ---
>  configure | 50 ++++++++++++++++++++++++++++++++------------------
>  1 file changed, 32 insertions(+), 18 deletions(-)
>
> diff --git a/configure b/configure
> index 233c671aaa..82143e8a41 100755
> --- a/configure
> +++ b/configure
> @@ -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
> --