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

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

Alex Bennée <alex.bennee@linaro.org> writes:

> 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

I did the following:

modified   Makefile
@@ -322,6 +322,7 @@ endif
 ifdef CONFIG_TRACE_SYSTEMTAP
 DOCS+=scripts/qemu-trace-stap.1
 endif
+DOCS+=sphinxdocs
 else
 DOCS=
 endif
@@ -401,7 +402,7 @@ dummy := $(call unnest-vars,, \

 include $(SRC_PATH)/tests/Makefile.include

-all: $(DOCS) sphinxdocs $(TOOLS) $(HELPERS-y) recurse-all modules
+all: $(DOCS) $(TOOLS) $(HELPERS-y) recurse-all modules

 qemu-version.h: FORCE
 	$(call quiet-command, \
@@ -699,13 +700,7 @@ for d in $$(cd docs && find $1 -type d); do $(INSTALL_DIR) "$(DESTDIR)$(qemu_doc
 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-doc: $(DOCS)
 	$(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)"
 	$(INSTALL_DATA) qemu-doc.html "$(DESTDIR)$(qemu_docdir)"
 	$(INSTALL_DATA) qemu-doc.txt "$(DESTDIR)$(qemu_docdir)"
@@ -737,6 +732,7 @@ ifdef CONFIG_VIRTFS
 	$(INSTALL_DIR) "$(DESTDIR)$(mandir)/man1"
 	$(INSTALL_DATA) fsdev/virtfs-proxy-helper.1 "$(DESTDIR)$(mandir)/man1"
 endif
+	$(call install-manual,interop)

 install-datadir:
 	$(INSTALL_DIR) "$(DESTDIR)$(qemu_datadir)"

--
Alex Bennée