* [PATCH 0/2] configure: Check that sphinx-build is using Python 3 @ 2020-02-03 13:25 Peter Maydell 2020-02-03 13:25 ` [PATCH 1/2] configure: Allow user to specify sphinx-build binary Peter Maydell 2020-02-03 13:25 ` [PATCH 2/2] configure: Check that sphinx-build is using Python 3 Peter Maydell 0 siblings, 2 replies; 9+ messages in thread From: Peter Maydell @ 2020-02-03 13:25 UTC (permalink / raw) To: qemu-devel; +Cc: Alex Bennée 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. At the moment our Sphinx extensions all work under Python 2, but the one I'm working on for handling parsing QAPI docs out of the JSON is going to want to include some of the scripts/qapi Python which is more complicated and definitely now 3-only. In any case, allowing some bits of our Python code to run under Python 2 is setting a beartrap for our future selves. It's nicer to fail cleanly rather than let users stumble into corner cases we don't test and don't want to support even if they happen to work today. Patch 1 adds a --sphinx-build=/path/to/binary option, so that if the user has a system where the default 'sphinx-build' on the $PATH is Python 2 they can tell configure to use a different one. Patch 2 makes the Sphinx conf.py fail for old Pythons, and makes configure handle and present the error to the user. Alex: do you have a way to test this patchset with readthedocs before it hits master? I'm not sure what version of Python their sphinx-build is using. If we need to I think we can force a Python version with a .readthedocs.yml file in our git repo: https://docs.readthedocs.io/en/stable/config-file/v2.html but if they default to a new enough Python anyway then we needn't bother. thanks -- PMM Peter Maydell (2): configure: Allow user to specify sphinx-build binary configure: Check that sphinx-build is using Python 3 configure | 22 +++++++++++++++++++--- Makefile | 2 +- docs/conf.py | 10 ++++++++++ 3 files changed, 30 insertions(+), 4 deletions(-) -- 2.20.1 ^ permalink raw reply [flat|nested] 9+ messages in thread
* [PATCH 1/2] configure: Allow user to specify sphinx-build binary 2020-02-03 13:25 [PATCH 0/2] configure: Check that sphinx-build is using Python 3 Peter Maydell @ 2020-02-03 13:25 ` Peter Maydell 2020-02-03 18:08 ` Alex Bennée ` (2 more replies) 2020-02-03 13:25 ` [PATCH 2/2] configure: Check that sphinx-build is using Python 3 Peter Maydell 1 sibling, 3 replies; 9+ messages in thread From: Peter Maydell @ 2020-02-03 13:25 UTC (permalink / raw) To: qemu-devel; +Cc: Alex Bennée Currently we insist on using 'sphinx-build' from the $PATH; allow the user to specify the binary to use. This will be more useful as we become pickier about the capabilities we require (eg needing a Python 3 sphinx-build). Signed-off-by: Peter Maydell <peter.maydell@linaro.org> --- I went with the most common convention for specifying "here's an executable", like --make=, --install=, --python=.... The only odd one out for our current configure options seems to be that we want --with-git=GIT, not --git=GIT. You could argue that that's a better convention, but it makes more sense to me to stick with the convention we currently mostly have. (Perhaps we should even change --with-git= to --git= ?) configure | 10 +++++++++- Makefile | 2 +- 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/configure b/configure index 5095f017283..830f325822a 100755 --- a/configure +++ b/configure @@ -584,6 +584,7 @@ query_pkg_config() { } 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}" @@ -975,6 +976,8 @@ for opt do ;; --python=*) python="$optarg" ;; + --sphinx-build=*) sphinx_build="$optarg" + ;; --gcov=*) gcov_tool="$optarg" ;; --smbd=*) smbd="$optarg" @@ -1677,6 +1680,7 @@ Advanced options (experts only): --make=MAKE use specified make [$make] --install=INSTALL use specified install [$install] --python=PYTHON use specified python [$python] + --sphinx-build=SPHINX use specified sphinx-build [$sphinx_build] --smbd=SMBD use specified smbd [$smbd] --with-git=GIT use specified git [$git] --static enable static build [$static] @@ -4799,7 +4803,7 @@ has_sphinx_build() { # 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 + $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. @@ -6474,6 +6478,9 @@ echo "QEMU_LDFLAGS $QEMU_LDFLAGS" echo "make $make" echo "install $install" echo "python $python ($python_version)" +if test "$docs" != "no"; then + echo "sphinx-build $sphinx_build" +fi echo "slirp support $slirp $(echo_version $slirp $slirp_version)" if test "$slirp" != "no" ; then echo "smbd $smbd" @@ -7503,6 +7510,7 @@ echo "INSTALL_DATA=$install -c -m 0644" >> $config_host_mak echo "INSTALL_PROG=$install -c -m 0755" >> $config_host_mak echo "INSTALL_LIB=$install -c -m 0644" >> $config_host_mak echo "PYTHON=$python" >> $config_host_mak +echo "SPHINX_BUILD=$sphinx_build" >> $config_host_mak echo "CC=$cc" >> $config_host_mak if $iasl -h > /dev/null 2>&1; then echo "IASL=$iasl" >> $config_host_mak diff --git a/Makefile b/Makefile index a6f5d440828..1f37523b528 100644 --- a/Makefile +++ b/Makefile @@ -1024,7 +1024,7 @@ sphinxdocs: $(MANUAL_BUILDDIR)/devel/index.html \ # Note the use of different doctree for each (manual, builder) tuple; # this works around Sphinx not handling parallel invocation on # a single doctree: https://github.com/sphinx-doc/sphinx/issues/2946 -build-manual = $(call quiet-command,CONFDIR="$(qemu_confdir)" sphinx-build $(if $(V),,-q) -W -b $2 -D version=$(VERSION) -D release="$(FULL_VERSION)" -d .doctrees/$1-$2 $(SRC_PATH)/docs/$1 $(MANUAL_BUILDDIR)/$1 ,"SPHINX","$(MANUAL_BUILDDIR)/$1") +build-manual = $(call quiet-command,CONFDIR="$(qemu_confdir)" $(SPHINX_BUILD) $(if $(V),,-q) -W -b $2 -D version=$(VERSION) -D release="$(FULL_VERSION)" -d .doctrees/$1-$2 $(SRC_PATH)/docs/$1 $(MANUAL_BUILDDIR)/$1 ,"SPHINX","$(MANUAL_BUILDDIR)/$1") # We assume all RST files in the manual's directory are used in it manual-deps = $(wildcard $(SRC_PATH)/docs/$1/*.rst) \ $(wildcard $(SRC_PATH)/docs/$1/*.rst.inc) \ -- 2.20.1 ^ permalink raw reply related [flat|nested] 9+ messages in thread
* Re: [PATCH 1/2] configure: Allow user to specify sphinx-build binary 2020-02-03 13:25 ` [PATCH 1/2] configure: Allow user to specify sphinx-build binary Peter Maydell @ 2020-02-03 18:08 ` Alex Bennée 2020-02-04 10:39 ` Markus Armbruster 2020-02-04 13:53 ` Wainer dos Santos Moschetta 2 siblings, 0 replies; 9+ messages in thread From: Alex Bennée @ 2020-02-03 18:08 UTC (permalink / raw) To: Peter Maydell; +Cc: qemu-devel Peter Maydell <peter.maydell@linaro.org> writes: > Currently we insist on using 'sphinx-build' from the $PATH; > allow the user to specify the binary to use. This will be > more useful as we become pickier about the capabilities > we require (eg needing a Python 3 sphinx-build). > > Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> > --- > I went with the most common convention for specifying "here's > an executable", like --make=, --install=, --python=.... > > The only odd one out for our current configure options seems to be > that we want --with-git=GIT, not --git=GIT. You could argue that > that's a better convention, but it makes more sense to me to > stick with the convention we currently mostly have. (Perhaps > we should even change --with-git= to --git= ?) > > configure | 10 +++++++++- > Makefile | 2 +- > 2 files changed, 10 insertions(+), 2 deletions(-) > > diff --git a/configure b/configure > index 5095f017283..830f325822a 100755 > --- a/configure > +++ b/configure > @@ -584,6 +584,7 @@ query_pkg_config() { > } > 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}" > @@ -975,6 +976,8 @@ for opt do > ;; > --python=*) python="$optarg" > ;; > + --sphinx-build=*) sphinx_build="$optarg" > + ;; > --gcov=*) gcov_tool="$optarg" > ;; > --smbd=*) smbd="$optarg" > @@ -1677,6 +1680,7 @@ Advanced options (experts only): > --make=MAKE use specified make [$make] > --install=INSTALL use specified install [$install] > --python=PYTHON use specified python [$python] > + --sphinx-build=SPHINX use specified sphinx-build [$sphinx_build] > --smbd=SMBD use specified smbd [$smbd] > --with-git=GIT use specified git [$git] > --static enable static build [$static] > @@ -4799,7 +4803,7 @@ has_sphinx_build() { > # 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 > + $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. > @@ -6474,6 +6478,9 @@ echo "QEMU_LDFLAGS $QEMU_LDFLAGS" > echo "make $make" > echo "install $install" > echo "python $python ($python_version)" > +if test "$docs" != "no"; then > + echo "sphinx-build $sphinx_build" > +fi > echo "slirp support $slirp $(echo_version $slirp $slirp_version)" > if test "$slirp" != "no" ; then > echo "smbd $smbd" > @@ -7503,6 +7510,7 @@ echo "INSTALL_DATA=$install -c -m 0644" >> $config_host_mak > echo "INSTALL_PROG=$install -c -m 0755" >> $config_host_mak > echo "INSTALL_LIB=$install -c -m 0644" >> $config_host_mak > echo "PYTHON=$python" >> $config_host_mak > +echo "SPHINX_BUILD=$sphinx_build" >> $config_host_mak > echo "CC=$cc" >> $config_host_mak > if $iasl -h > /dev/null 2>&1; then > echo "IASL=$iasl" >> $config_host_mak > diff --git a/Makefile b/Makefile > index a6f5d440828..1f37523b528 100644 > --- a/Makefile > +++ b/Makefile > @@ -1024,7 +1024,7 @@ sphinxdocs: $(MANUAL_BUILDDIR)/devel/index.html \ > # Note the use of different doctree for each (manual, builder) tuple; > # this works around Sphinx not handling parallel invocation on > # a single doctree: https://github.com/sphinx-doc/sphinx/issues/2946 > -build-manual = $(call quiet-command,CONFDIR="$(qemu_confdir)" sphinx-build $(if $(V),,-q) -W -b $2 -D version=$(VERSION) -D release="$(FULL_VERSION)" -d .doctrees/$1-$2 $(SRC_PATH)/docs/$1 $(MANUAL_BUILDDIR)/$1 ,"SPHINX","$(MANUAL_BUILDDIR)/$1") > +build-manual = $(call quiet-command,CONFDIR="$(qemu_confdir)" $(SPHINX_BUILD) $(if $(V),,-q) -W -b $2 -D version=$(VERSION) -D release="$(FULL_VERSION)" -d .doctrees/$1-$2 $(SRC_PATH)/docs/$1 $(MANUAL_BUILDDIR)/$1 ,"SPHINX","$(MANUAL_BUILDDIR)/$1") > # We assume all RST files in the manual's directory are used in it > manual-deps = $(wildcard $(SRC_PATH)/docs/$1/*.rst) \ > $(wildcard $(SRC_PATH)/docs/$1/*.rst.inc) \ -- Alex Bennée ^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH 1/2] configure: Allow user to specify sphinx-build binary 2020-02-03 13:25 ` [PATCH 1/2] configure: Allow user to specify sphinx-build binary Peter Maydell 2020-02-03 18:08 ` Alex Bennée @ 2020-02-04 10:39 ` Markus Armbruster 2020-02-04 12:37 ` Paolo Bonzini 2020-02-04 13:53 ` Wainer dos Santos Moschetta 2 siblings, 1 reply; 9+ messages in thread From: Markus Armbruster @ 2020-02-04 10:39 UTC (permalink / raw) To: Peter Maydell; +Cc: Paolo Bonzini, Alex Bennée, qemu-devel Peter Maydell <peter.maydell@linaro.org> writes: > Currently we insist on using 'sphinx-build' from the $PATH; > allow the user to specify the binary to use. This will be > more useful as we become pickier about the capabilities > we require (eg needing a Python 3 sphinx-build). > > Signed-off-by: Peter Maydell <peter.maydell@linaro.org> > --- > I went with the most common convention for specifying "here's > an executable", like --make=, --install=, --python=.... > > The only odd one out for our current configure options seems to be > that we want --with-git=GIT, not --git=GIT. You could argue that > that's a better convention, It's the one Autoconf uses. > but it makes more sense to me to > stick with the convention we currently mostly have. (Perhaps > we should even change --with-git= to --git= ?) Paolo, any implications on the Meson conversion? ^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH 1/2] configure: Allow user to specify sphinx-build binary 2020-02-04 10:39 ` Markus Armbruster @ 2020-02-04 12:37 ` Paolo Bonzini 0 siblings, 0 replies; 9+ messages in thread From: Paolo Bonzini @ 2020-02-04 12:37 UTC (permalink / raw) To: Markus Armbruster, Peter Maydell; +Cc: Alex Bennée, qemu-devel On 04/02/20 11:39, Markus Armbruster wrote: > Peter Maydell <peter.maydell@linaro.org> writes: > >> Currently we insist on using 'sphinx-build' from the $PATH; >> allow the user to specify the binary to use. This will be >> more useful as we become pickier about the capabilities >> we require (eg needing a Python 3 sphinx-build). >> >> Signed-off-by: Peter Maydell <peter.maydell@linaro.org> >> --- >> I went with the most common convention for specifying "here's >> an executable", like --make=, --install=, --python=.... >> >> The only odd one out for our current configure options seems to be >> that we want --with-git=GIT, not --git=GIT. You could argue that >> that's a better convention, > > It's the one Autoconf uses. > >> but it makes more sense to me to >> stick with the convention we currently mostly have. (Perhaps >> we should even change --with-git= to --git= ?) > > Paolo, any implications on the Meson conversion? Nope, there will still be a handwritten configure script (and in the beginning it will be pretty much the same as now; in due time, it will handle command line parsing only). Paolo ^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH 1/2] configure: Allow user to specify sphinx-build binary 2020-02-03 13:25 ` [PATCH 1/2] configure: Allow user to specify sphinx-build binary Peter Maydell 2020-02-03 18:08 ` Alex Bennée 2020-02-04 10:39 ` Markus Armbruster @ 2020-02-04 13:53 ` Wainer dos Santos Moschetta 2 siblings, 0 replies; 9+ messages in thread From: Wainer dos Santos Moschetta @ 2020-02-04 13:53 UTC (permalink / raw) To: Peter Maydell, qemu-devel; +Cc: Alex Bennée On 2/3/20 11:25 AM, Peter Maydell wrote: > Currently we insist on using 'sphinx-build' from the $PATH; > allow the user to specify the binary to use. This will be > more useful as we become pickier about the capabilities > we require (eg needing a Python 3 sphinx-build). > > Signed-off-by: Peter Maydell <peter.maydell@linaro.org> > --- > I went with the most common convention for specifying "here's > an executable", like --make=, --install=, --python=.... > > The only odd one out for our current configure options seems to be > that we want --with-git=GIT, not --git=GIT. You could argue that > that's a better convention, but it makes more sense to me to > stick with the convention we currently mostly have. (Perhaps > we should even change --with-git= to --git= ?) > > configure | 10 +++++++++- > Makefile | 2 +- > 2 files changed, 10 insertions(+), 2 deletions(-) Reviewed-by: Wainer dos Santos Moschetta <wainersm@redhat.com> > > diff --git a/configure b/configure > index 5095f017283..830f325822a 100755 > --- a/configure > +++ b/configure > @@ -584,6 +584,7 @@ query_pkg_config() { > } > 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}" > @@ -975,6 +976,8 @@ for opt do > ;; > --python=*) python="$optarg" > ;; > + --sphinx-build=*) sphinx_build="$optarg" > + ;; > --gcov=*) gcov_tool="$optarg" > ;; > --smbd=*) smbd="$optarg" > @@ -1677,6 +1680,7 @@ Advanced options (experts only): > --make=MAKE use specified make [$make] > --install=INSTALL use specified install [$install] > --python=PYTHON use specified python [$python] > + --sphinx-build=SPHINX use specified sphinx-build [$sphinx_build] > --smbd=SMBD use specified smbd [$smbd] > --with-git=GIT use specified git [$git] > --static enable static build [$static] > @@ -4799,7 +4803,7 @@ has_sphinx_build() { > # 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 > + $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. > @@ -6474,6 +6478,9 @@ echo "QEMU_LDFLAGS $QEMU_LDFLAGS" > echo "make $make" > echo "install $install" > echo "python $python ($python_version)" > +if test "$docs" != "no"; then > + echo "sphinx-build $sphinx_build" > +fi > echo "slirp support $slirp $(echo_version $slirp $slirp_version)" > if test "$slirp" != "no" ; then > echo "smbd $smbd" > @@ -7503,6 +7510,7 @@ echo "INSTALL_DATA=$install -c -m 0644" >> $config_host_mak > echo "INSTALL_PROG=$install -c -m 0755" >> $config_host_mak > echo "INSTALL_LIB=$install -c -m 0644" >> $config_host_mak > echo "PYTHON=$python" >> $config_host_mak > +echo "SPHINX_BUILD=$sphinx_build" >> $config_host_mak > echo "CC=$cc" >> $config_host_mak > if $iasl -h > /dev/null 2>&1; then > echo "IASL=$iasl" >> $config_host_mak > diff --git a/Makefile b/Makefile > index a6f5d440828..1f37523b528 100644 > --- a/Makefile > +++ b/Makefile > @@ -1024,7 +1024,7 @@ sphinxdocs: $(MANUAL_BUILDDIR)/devel/index.html \ > # Note the use of different doctree for each (manual, builder) tuple; > # this works around Sphinx not handling parallel invocation on > # a single doctree: https://github.com/sphinx-doc/sphinx/issues/2946 > -build-manual = $(call quiet-command,CONFDIR="$(qemu_confdir)" sphinx-build $(if $(V),,-q) -W -b $2 -D version=$(VERSION) -D release="$(FULL_VERSION)" -d .doctrees/$1-$2 $(SRC_PATH)/docs/$1 $(MANUAL_BUILDDIR)/$1 ,"SPHINX","$(MANUAL_BUILDDIR)/$1") > +build-manual = $(call quiet-command,CONFDIR="$(qemu_confdir)" $(SPHINX_BUILD) $(if $(V),,-q) -W -b $2 -D version=$(VERSION) -D release="$(FULL_VERSION)" -d .doctrees/$1-$2 $(SRC_PATH)/docs/$1 $(MANUAL_BUILDDIR)/$1 ,"SPHINX","$(MANUAL_BUILDDIR)/$1") > # We assume all RST files in the manual's directory are used in it > manual-deps = $(wildcard $(SRC_PATH)/docs/$1/*.rst) \ > $(wildcard $(SRC_PATH)/docs/$1/*.rst.inc) \ ^ permalink raw reply [flat|nested] 9+ messages in thread
* [PATCH 2/2] configure: Check that sphinx-build is using Python 3 2020-02-03 13:25 [PATCH 0/2] configure: Check that sphinx-build is using Python 3 Peter Maydell 2020-02-03 13:25 ` [PATCH 1/2] configure: Allow user to specify sphinx-build binary Peter Maydell @ 2020-02-03 13:25 ` Peter Maydell 2020-02-03 18:09 ` Alex Bennée 2020-02-04 13:58 ` Wainer dos Santos Moschetta 1 sibling, 2 replies; 9+ messages in thread From: Peter Maydell @ 2020-02-03 13:25 UTC (permalink / raw) To: qemu-devel; +Cc: Alex Bennée 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 <peter.maydell@linaro.org> --- At the moment our Sphinx extensions all work under Python 2; but the one for handling parsing QAPI docs out of the JSON is going to want to include some of the scripts/qapi Python which is more complicated and definitely now 3-only. In any case it's nicer to fail cleanly rather than let users stumble into corner cases we don't test and don't want to support even if they happen to work today. --- configure | 12 ++++++++++-- docs/conf.py | 10 ++++++++++ 2 files changed, 20 insertions(+), 2 deletions(-) diff --git a/configure b/configure index 830f325822a..95055f2e9dd 100755 --- a/configure +++ b/configure @@ -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. -- 2.20.1 ^ permalink raw reply related [flat|nested] 9+ messages in thread
* Re: [PATCH 2/2] configure: Check that sphinx-build is using Python 3 2020-02-03 13:25 ` [PATCH 2/2] configure: Check that sphinx-build is using Python 3 Peter Maydell @ 2020-02-03 18:09 ` Alex Bennée 2020-02-04 13:58 ` Wainer dos Santos Moschetta 1 sibling, 0 replies; 9+ messages in thread From: Alex Bennée @ 2020-02-03 18:09 UTC (permalink / raw) To: Peter Maydell; +Cc: qemu-devel Peter Maydell <peter.maydell@linaro.org> 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 <peter.maydell@linaro.org> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> > --- > At the moment our Sphinx extensions all work under Python 2; > but the one for handling parsing QAPI docs out of the JSON is going > to want to include some of the scripts/qapi Python which is more > complicated and definitely now 3-only. In any case it's nicer to > fail cleanly rather than let users stumble into corner cases we don't > test and don't want to support even if they happen to work today. > --- > configure | 12 ++++++++++-- > docs/conf.py | 10 ++++++++++ > 2 files changed, 20 insertions(+), 2 deletions(-) > > diff --git a/configure b/configure > index 830f325822a..95055f2e9dd 100755 > --- a/configure > +++ b/configure > @@ -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. -- Alex Bennée ^ permalink raw reply [flat|nested] 9+ messages in thread
* Re: [PATCH 2/2] configure: Check that sphinx-build is using Python 3 2020-02-03 13:25 ` [PATCH 2/2] configure: Check that sphinx-build is using Python 3 Peter Maydell 2020-02-03 18:09 ` Alex Bennée @ 2020-02-04 13:58 ` Wainer dos Santos Moschetta 1 sibling, 0 replies; 9+ messages in thread From: Wainer dos Santos Moschetta @ 2020-02-04 13:58 UTC (permalink / raw) To: Peter Maydell, qemu-devel; +Cc: Alex Bennée On 2/3/20 11:25 AM, Peter Maydell wrote: > 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 <peter.maydell@linaro.org> > --- > At the moment our Sphinx extensions all work under Python 2; > but the one for handling parsing QAPI docs out of the JSON is going > to want to include some of the scripts/qapi Python which is more > complicated and definitely now 3-only. In any case it's nicer to > fail cleanly rather than let users stumble into corner cases we don't > test and don't want to support even if they happen to work today. > --- > configure | 12 ++++++++++-- > docs/conf.py | 10 ++++++++++ > 2 files changed, 20 insertions(+), 2 deletions(-) Reviewed-by: Wainer dos Santos Moschetta <wainersm@redhat.com> > > diff --git a/configure b/configure > index 830f325822a..95055f2e9dd 100755 > --- a/configure > +++ b/configure > @@ -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. ^ permalink raw reply [flat|nested] 9+ messages in thread
end of thread, other threads:[~2020-02-04 13:59 UTC | newest] Thread overview: 9+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2020-02-03 13:25 [PATCH 0/2] configure: Check that sphinx-build is using Python 3 Peter Maydell 2020-02-03 13:25 ` [PATCH 1/2] configure: Allow user to specify sphinx-build binary Peter Maydell 2020-02-03 18:08 ` Alex Bennée 2020-02-04 10:39 ` Markus Armbruster 2020-02-04 12:37 ` Paolo Bonzini 2020-02-04 13:53 ` Wainer dos Santos Moschetta 2020-02-03 13:25 ` [PATCH 2/2] configure: Check that sphinx-build is using Python 3 Peter Maydell 2020-02-03 18:09 ` Alex Bennée 2020-02-04 13:58 ` Wainer dos Santos Moschetta
This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).