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

[John Snow]

On 4/15/20 1:55 PM, Peter Maydell wrote:
> On Wed, 15 Apr 2020 at 18:33, John Snow <address@hidden> 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.)
> 

I'll take your word for it :)

> 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

>> 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 <address@hidden>
>> ---
>>  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
>> --
>