Message ID | 20190305172139.32662-10-peter.maydell@linaro.org (mailing list archive) |
---|---|
State | New, archived |
Headers | show |
Series | Enable build and install of our rST docs | expand |
On 3/5/19 9:21 AM, Peter Maydell wrote: > 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.) > > Signed-off-by: Peter Maydell <peter.maydell@linaro.org> > Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com> > Tested-by: Philippe Mathieu-Daudé <philmd@redhat.com> > Acked-by: Aleksandar Markovic <amarkovic@wavecomp.com> > Message-id: 20190228145624.24885-10-peter.maydell@linaro.org > --- > configure | 15 +++++++++++++-- > Makefile | 45 ++++++++++++++++++++++++++++++++++++++++++--- > .gitignore | 1 + > 3 files changed, 56 insertions(+), 5 deletions(-) Reviewed-by: Richard Henderson <richard.henderson@linaro.org> r~
On 3/5/19 11:21 AM, Peter Maydell wrote: > 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.) > > Signed-off-by: Peter Maydell <peter.maydell@linaro.org> > Reviewed-by: Philippe Mathieu-Daudé <philmd@redhat.com> > Tested-by: Philippe Mathieu-Daudé <philmd@redhat.com> > Acked-by: Aleksandar Markovic <amarkovic@wavecomp.com> > Message-id: 20190228145624.24885-10-peter.maydell@linaro.org Rich told me that qemu-nbd.8 was not being built, and I confirmed that it failed to build for me. git bisect points to this commit as the reason that 'touch qemu-nbd.texi; make' no longer rebuilds qemu-nbd.8 automatically. Is it merely because I don't have enough stuff installed, or is it an actual broken dependency? /me goes and runs 'dnf install "*/sphinx-build"... Nope, even with that installed, qemu-nbd.8 is still not getting built by 'make'; but 'make qemu-nbd.8' is working. We lost a dependency :(
On Sat, 30 Mar 2019 at 22:05, Eric Blake <eblake@redhat.com> wrote: > Rich told me that qemu-nbd.8 was not being built, and I confirmed that > it failed to build for me. git bisect points to this commit as the > reason that 'touch qemu-nbd.texi; make' no longer rebuilds qemu-nbd.8 > automatically. Is it merely because I don't have enough stuff installed, > or is it an actual broken dependency? > > /me goes and runs 'dnf install "*/sphinx-build"... > > Nope, even with that installed, qemu-nbd.8 is still not getting built by > 'make'; but 'make qemu-nbd.8' is working. We lost a dependency :( I just did a test build from clean and I get a qemu-nbd.8 in the build directory. I also checked that 'touch qemu-nbd.texi; make -C build V=1' rebuilds the manpage, and it does: [snip other stuff] perl -Ww -- /home/pm215/qemu/scripts/texi2pod.pl -I docs -I /home/pm215/qemu -I . "-DVERSION=3.1.91" /home/pm215/qemu/qemu-nbd.texi qemu-nbd.8.pod && pod2man --utf8 --section=8 --center=" " --release=" " qemu-nbd.8.pod > qemu-nbd.8 [...] You will need sphinx-build in order to build the docs now, and without that we won't build the manpage, but if you have sphinx-build installed then it should work. Can you check that your config-host.mak has BUILD_DOCS=yes ? Did you definitely rerun configure after installing sphinx? thanks -- PMM
On 4/1/19 2:58 AM, Peter Maydell wrote: > On Sat, 30 Mar 2019 at 22:05, Eric Blake <eblake@redhat.com> wrote: >> Rich told me that qemu-nbd.8 was not being built, and I confirmed that >> it failed to build for me. git bisect points to this commit as the >> reason that 'touch qemu-nbd.texi; make' no longer rebuilds qemu-nbd.8 >> automatically. Is it merely because I don't have enough stuff installed, >> or is it an actual broken dependency? >> >> /me goes and runs 'dnf install "*/sphinx-build"... >> >> Nope, even with that installed, qemu-nbd.8 is still not getting built by >> 'make'; but 'make qemu-nbd.8' is working. We lost a dependency :( > > I just did a test build from clean and I get a qemu-nbd.8 in the > build directory. I also checked that 'touch qemu-nbd.texi; make -C build V=1' > rebuilds the manpage, and it does: > > [snip other stuff] > perl -Ww -- /home/pm215/qemu/scripts/texi2pod.pl -I docs -I > /home/pm215/qemu -I . "-DVERSION=3.1.91" > /home/pm215/qemu/qemu-nbd.texi qemu-nbd.8.pod && pod2man --utf8 > --section=8 --center=" " --release=" " qemu-nbd.8.pod > qemu-nbd.8 > [...] > > You will need sphinx-build in order to build > the docs now, and without that we won't build the manpage, but > if you have sphinx-build installed then it should work. > Can you check that your config-host.mak has BUILD_DOCS=yes ? Not seeing it. > Did you definitely rerun configure after installing sphinx? Trying that again. I did not specify anything special to configure to force-enable/disable docs, so this time, it should auto-detect that sphinx-build is present... and now BUILD_DOCS=yes appears... And that fixes it. Thanks for helping me spot the added build dependency.
diff --git a/configure b/configure index cefeb8fcce4..47bf617fcc5 100755 --- a/configure +++ b/configure @@ -4589,13 +4589,24 @@ if compile_prog "" "" ; then syncfs=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 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 2208bde4196..add22cf2947 100644 --- a/Makefile +++ b/Makefile @@ -388,7 +388,7 @@ dummy := $(call unnest-vars,, \ include $(SRC_PATH)/tests/Makefile.include -all: $(DOCS) $(TOOLS) $(HELPERS-y) recurse-all modules +all: $(DOCS) $(if $(BUILD_DOCS),sphinxdocs) $(TOOLS) $(HELPERS-y) recurse-all modules qemu-version.h: FORCE $(call quiet-command, \ @@ -637,6 +637,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 -f 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 @@ -657,6 +665,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 @@ -690,7 +701,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)" @@ -841,6 +863,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","$@") @@ -869,7 +908,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 diff --git a/.gitignore b/.gitignore index b66b7725512..77522561b8e 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ +/.doctrees /config-devices.* /config-all-devices.* /config-all-disas.*