Re: [Qemu-devel] [PATCH 09/11] Makefile, configure: Support building rST documentation

["Alex Bennée" <alex.bennee@linaro.org>]

Peter Maydell <peter.maydell@linaro.org> writes:

> Add support to our configure and makefile machinery for building
> our rST docs into HTML files.
>
> Building the documentation now requires that sphinx-build is
> available; this seems better than allowing half the docs to
> be built if it is not present but having half of them missing.
> (In particular it means that assuming that distros configured with
> --enable-docs they'll get a helpful error from configure telling
> them the new build dependency.)

Hmm we manage to break Travis CI:

  https://travis-ci.org/stsquad/qemu/jobs/487512292#L902

It reports:

  Documentation     no

But then proceeds to barf:

  https://travis-ci.org/stsquad/qemu/jobs/487512292#L1395

with:

  /bin/sh: 1: sphinx-build: not found
  Makefile:871: recipe for target 'docs/devel/index.html' failed
  make: *** [docs/devel/index.html] Error 127

>
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---
>  configure |  4 ++--
>  Makefile  | 45 ++++++++++++++++++++++++++++++++++++++++++---
>  2 files changed, 44 insertions(+), 5 deletions(-)
>
> diff --git a/configure b/configure
> index b18281c61f3..9cd5c0cd0bd 100755
> --- a/configure
> +++ b/configure
> @@ -4561,11 +4561,11 @@ fi
>
>  # Check if tools are available to build documentation.
>  if test "$docs" != "no" ; then
> -  if has makeinfo && has pod2man; then
> +  if has makeinfo && has pod2man && has sphinx-build; then
>      docs=yes
>    else
>      if test "$docs" = "yes" ; then
> -      feature_not_found "docs" "Install texinfo and Perl/perl-podlators"
> +      feature_not_found "docs" "Install texinfo, Perl/perl-podlators and python-sphinx"
>      fi
>      docs=no
>    fi
> diff --git a/Makefile b/Makefile
> index 1278a3eb529..d519fadee39 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -387,7 +387,7 @@ dummy := $(call unnest-vars,, \
>
>  include $(SRC_PATH)/tests/Makefile.include
>
> -all: $(DOCS) $(TOOLS) $(HELPERS-y) recurse-all modules
> +all: $(DOCS) sphinxdocs $(TOOLS) $(HELPERS-y) recurse-all modules
>
>  qemu-version.h: FORCE
>  	$(call quiet-command, \
> @@ -631,6 +631,14 @@ dist: qemu-$(VERSION).tar.bz2
>  qemu-%.tar.bz2:
>  	$(SRC_PATH)/scripts/make-release "$(SRC_PATH)" "$(patsubst qemu-%.tar.bz2,%,$@)"
>
> +# Note that these commands assume that there are no HTML files in
> +# the docs subdir in the source tree! If there are then this will
> +# blow them away for an in-source-tree 'make clean'.
> +define clean-manual =
> +rm -rf docs/$1/_static
> +rm docs/$1/objects.inv docs/$1/searchindex.js docs/$1/*.html
> +endef
> +
>  distclean: clean
>  	rm -f config-host.mak config-host.h* config-host.ld $(DOCS) qemu-options.texi qemu-img-cmds.texi qemu-monitor.texi qemu-monitor-info.texi
>  	rm -f config-all-devices.mak config-all-disas.mak config.status
> @@ -651,6 +659,9 @@ distclean: clean
>  	rm -f docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html
>  	rm -f docs/qemu-block-drivers.7
>  	rm -f docs/qemu-cpu-models.7
> +	rm -f .doctrees
> +	$(call clean-manual,devel)
> +	$(call clean-manual,interop)
>  	for d in $(TARGET_DIRS); do \
>  	rm -rf $$d || exit 1 ; \
>          done
> @@ -684,7 +695,18 @@ else
>  BLOBS=
>  endif
>
> -install-doc: $(DOCS)
> +define install-manual =
> +for d in $$(cd docs && find $1 -type d); do $(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)/$$d"; done
> +for f in $$(cd docs && find $1 -type f); do $(INSTALL_DATA) "docs/$$f" "$(DESTDIR)$(qemu_docdir)/$$f"; done
> +endef
> +
> +# Note that we deliberately do not install the "devel" manual: it is
> +# for QEMU developers, and not interesting to our users.
> +.PHONY: install-sphinxdocs
> +install-sphinxdocs: sphinxdocs
> +	$(call install-manual,interop)
> +
> +install-doc: $(DOCS) install-sphinxdocs
>  	$(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)"
>  	$(INSTALL_DATA) qemu-doc.html "$(DESTDIR)$(qemu_docdir)"
>  	$(INSTALL_DATA) qemu-doc.txt "$(DESTDIR)$(qemu_docdir)"
> @@ -835,6 +857,23 @@ docs/version.texi: $(SRC_PATH)/VERSION
>  %.pdf: %.texi docs/version.texi
>  	$(call quiet-command,texi2pdf $(TEXI2PDFFLAGS) $< -o $@,"GEN","$@")
>
> +# Sphinx builds all its documentation at once in one invocation
> +# and handles "don't rebuild things unless necessary" itself.
> +# The '.doctrees' files are cached information to speed this up.
> +.PHONY: sphinxdocs
> +sphinxdocs: docs/devel/index.html docs/interop/index.html
> +
> +# Canned command to build a single manual
> +build-manual = $(call quiet-command,sphinx-build $(if $(V),,-q) -b html -d .doctrees/$1 $(SRC_PATH)/docs/$1 docs/$1 ,"SPHINX","docs/$1")
> +# We assume all RST files in the manual's directory are used in it
> +manual-deps = $(wildcard $(SRC_PATH)/docs/$1/*.rst) $(SRC_PATH)/docs/$1/conf.py $(SRC_PATH)/docs/conf.py
> +
> +docs/devel/index.html: $(call manual-deps,devel)
> +	$(call build-manual,devel)
> +
> +docs/interop/index.html: $(call manual-deps,interop)
> +	$(call build-manual,interop)
> +
>  qemu-options.texi: $(SRC_PATH)/qemu-options.hx $(SRC_PATH)/scripts/hxtool
>  	$(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > $@,"GEN","$@")
>
> @@ -863,7 +902,7 @@ docs/qemu-block-drivers.7: docs/qemu-block-drivers.texi
>  docs/qemu-cpu-models.7: docs/qemu-cpu-models.texi
>  scripts/qemu-trace-stap.1: scripts/qemu-trace-stap.texi
>
> -html: qemu-doc.html docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html
> +html: qemu-doc.html docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html sphinxdocs
>  info: qemu-doc.info docs/interop/qemu-qmp-ref.info docs/interop/qemu-ga-ref.info
>  pdf: qemu-doc.pdf docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.pdf
>  txt: qemu-doc.txt docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.txt


--
Alex Bennée