Re: [PATCH 02/29] configure: Check that sphinx-build is using Python 3

[Markus Armbruster]

Peter Maydell <address@hidden> writes:

> Currently configure's has_sphinx_build() check simply runs a dummy
> sphinx-build and either passes or fails.  This means that "no
> sphinx-build at all" and "sphinx-build exists but is too old" are
> both reported the same way.
>
> Further, we want to assume that all the Python we write is running
> with at least Python 3.5; configure checks that for our scripts, but
> Sphinx extensions run with whatever Python version sphinx-build
> itself is using.
>
> Add a check to our conf.py which makes sphinx-build fail if it would
> be running our extensions with an old Python, and handle this
> in configure so we can report failure helpfully to the user.
> This will mean that configure --enable-docs will fail like this
> if the sphinx-build provided is not suitable:
>
> Warning: sphinx-build exists but it is either too old or uses too old a 
> Python version
>
> ERROR: User requested feature docs
>        configure was not able to find it.
>        Install texinfo, Perl/perl-podlators and a Python 3 version of 
> python-sphinx
>
> (As usual, the default is to simply not build the docs, as we would
> if sphinx-build wasn't present at all.)
>
> Signed-off-by: Peter Maydell <address@hidden>
> Reviewed-by: Alex Bennée <address@hidden>
> Reviewed-by: Wainer dos Santos Moschetta <address@hidden>
> ---
>  configure    | 12 ++++++++++--
>  docs/conf.py | 10 ++++++++++
>  2 files changed, 20 insertions(+), 2 deletions(-)
>
> diff --git a/configure b/configure
> index 0aceb8e50db..2c5cad13edd 100755
> --- a/configure
> +++ b/configure

Any particular reason for having $sphinx_build default to the
indeterminate version sphinx-build rather than sphinx-build-3?

It's here:

   pkg_config=query_pkg_config
   sdl2_config="${SDL2_CONFIG-${cross_prefix}sdl2-config}"
   sphinx_build=sphinx-build

   # If the user hasn't specified ARFLAGS, default to 'rv', just as make does.
   ARFLAGS="${ARFLAGS-rv}"

> @@ -4808,11 +4808,19 @@ has_sphinx_build() {
>  
>  # Check if tools are available to build documentation.
>  if test "$docs" != "no" ; then
> -  if has makeinfo && has pod2man && has_sphinx_build; then
> +  if has_sphinx_build; then
> +    sphinx_ok=yes
> +  else
> +    sphinx_ok=no
> +  fi
> +  if has makeinfo && has pod2man && test "$sphinx_ok" = "yes"; then
>      docs=yes
>    else
>      if test "$docs" = "yes" ; then
> -      feature_not_found "docs" "Install texinfo, Perl/perl-podlators and 
> python-sphinx"
> +      if has $sphinx_build && test "$sphinx_ok" != "yes"; then
> +        echo "Warning: $sphinx_build exists but it is either too old or uses 
> too old a Python version" >&2
> +      fi
> +      feature_not_found "docs" "Install texinfo, Perl/perl-podlators and a 
> Python 3 version of python-sphinx"
>      fi
>      docs=no
>    fi
> diff --git a/docs/conf.py b/docs/conf.py
> index ee7faa6b4e7..7588bf192ee 100644
> --- a/docs/conf.py
> +++ b/docs/conf.py
> @@ -28,6 +28,16 @@
>  
>  import os
>  import sys
> +import sphinx
> +from sphinx.errors import VersionRequirementError
> +
> +# Make Sphinx fail cleanly if using an old Python, rather than obscurely
> +# failing because some code in one of our extensions doesn't work there.
> +# Unfortunately this doesn't display very neatly (there's an unavoidable
> +# Python backtrace) but at least the information gets printed...
> +if sys.version_info < (3,5):
> +    raise VersionRequirementError(
> +        "QEMU requires a Sphinx that uses Python 3.5 or better\n")
>  
>  # The per-manual conf.py will set qemu_docdir for a single-manual build;
>  # otherwise set it here if this is an entire-manual-set build.