From patchwork Thu Feb 28 14:56:22 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 159394 Delivered-To: patches@linaro.org Received: by 2002:a02:5cc1:0:0:0:0:0 with SMTP id w62csp736477jad; Thu, 28 Feb 2019 06:56:54 -0800 (PST) X-Received: by 2002:adf:dd12:: with SMTP id a18mr6250888wrm.4.1551365814143; Thu, 28 Feb 2019 06:56:54 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1551365814; cv=none; d=google.com; s=arc-20160816; b=OvZletW7ABDFTENeCHLhLflilIRJsGTZ4U5Bmrht08jFI4oY2HnLh+BEFG2n5wKh0f fDFiRIpsgfxru+tnMfBoFY0hSNw21OWDr/WTeouzvVclhi/xeYNaKjAK+iuMnU/l/iyE +fS8GxJ5hox815q0/teFb8AJtIvKxPT3qZiXYF6tV9s1FcnMEaV62jmx07BTSWgj+YUi j1UfhSM+JTc930lr5qdDQkoOW9FupFdx0bgLYNNVqeEpIVMKnmZJfJHRBY6dMNseCcGB ubEawvAai/wIwSeeVIrs1FS9PAKuF23+rY1gCRXybNqoQXL3tF106DDw0ua4dGLU0lX+ 7eAA== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:dkim-signature; bh=JizI2snDTt/q5TvanQhB9H8Wp5MTg1y47uEtiAt+lJM=; b=qzpGhDGM2WK6E9dHNYJUSApElyjTlP/LDG7sblMsSVmluxXDbLoNiYHixfhCfa/Vc7 Dctq4SZYBGF2XpBFysb9k7E/qkqnYV080Ow+2xAFZXTHKqUjDndCN8u5FJt45vTUR4zP xmiCxPPbAJl6sxP9p2NurP3OleTm/AqZYWd0uxOITPjanDtGw62sEjOS7QW7okNyKH0G +FLifbDSnppDFCYijWAvNbbBKJ48wkKrBHZB7eCqg7AzUyB6rXEXaYlMIUcbPO3KiCNO h/5n2WF272u1LHChF7EYXabVZMZlDs9hPMI6uEScQ+coEFhqxyjfUzX/411941zp3S2D op/Q== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=PKe1I1jE; spf=pass (google.com: domain of peter.maydell@linaro.org designates 209.85.220.65 as permitted sender) smtp.mailfrom=peter.maydell@linaro.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from mail-sor-f65.google.com (mail-sor-f65.google.com. [209.85.220.65]) by mx.google.com with SMTPS id o206sor3509795wma.11.2019.02.28.06.56.54 for (Google Transport Security); Thu, 28 Feb 2019 06:56:54 -0800 (PST) Received-SPF: pass (google.com: domain of peter.maydell@linaro.org designates 209.85.220.65 as permitted sender) client-ip=209.85.220.65; Authentication-Results: mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=PKe1I1jE; spf=pass (google.com: domain of peter.maydell@linaro.org designates 209.85.220.65 as permitted sender) smtp.mailfrom=peter.maydell@linaro.org; dmarc=pass (p=NONE sp=NONE dis=NONE) header.from=linaro.org DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=linaro.org; s=google; h=from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=JizI2snDTt/q5TvanQhB9H8Wp5MTg1y47uEtiAt+lJM=; b=PKe1I1jEDB1BMGBAjhCOdjdwOCi0gZz4IhfdSRBxpU+XtbP60WkdZ/eJ/Lt1gScp/A POzx2x4XW7xI4S9bMkw+K+JhT7i3C8LBok/DRXeo6J8GiaUeMsHkg+8tfWTHa+dB9Xx1 SVm6wz8fGaU2vHLbCyYOv+2TADrrCS2LoEgOb5P9QXUUUrUYPInB6ZLc1ddFFEiRxPJ7 AXGxbpt/IkxOcHZWHj23cS11LohZqZeydjM0pvBAYklia7n7OE2iyhcwBMD9PenZuMWi Ho4oHAsPDNPeumCWt/jUpn3HFW/NSGV8uxb+28Zoo5sIwORhs7qrlEqMhjuhkNEl5okO hyQQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:from:to:cc:subject:date:message-id:in-reply-to :references:mime-version:content-transfer-encoding; bh=JizI2snDTt/q5TvanQhB9H8Wp5MTg1y47uEtiAt+lJM=; b=pNErFfWaUMwVzDAq87UT/z6ZCtDJVXpmjNCpgZnsr+kSajNm7U3enuNWrM+ooqYT9F JXgJJ43W2L7YTLxfL1hvbqXS1a9p1WADM6aHtYOzfHxGvkxMQujpdvZVvNum4JtVPzNS va+SbOSUQNoqqdkBPCTtArIkFaaShSUz2zl3IW9/lcvOLmgMZMme1xmwxI378HdpnVyn CKmh7+obTgcXi167HTCJJ8LmpRShwlfm/XdsIkkip4EFarXlj+8ahzFR+H7K+EByxVJE D5y1E6zSFETMapyKbeJiMKr0uSUCXPYUDd+P/PLh4uStq8DhHU2l+hPMDBgsGyKGnig6 US+A== X-Gm-Message-State: APjAAAVHV89kPEXqU7/7eTTGhX1dTPYz1WUQhkpZdTgXvHtXmixhUF/+ p2FuLwrXR1s+ez/1UYudZ/o3440V X-Google-Smtp-Source: AHgI3IYI8PRzUlW55m8qJjGFojN3xlh+KSl6tsRart6igCkkA7DXG2skVCvGtIuciLniBcTU7t4l1w== X-Received: by 2002:a7b:c929:: with SMTP id h9mr73011wml.106.1551365813667; Thu, 28 Feb 2019 06:56:53 -0800 (PST) Return-Path: Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id c17sm14047539wrs.17.2019.02.28.06.56.50 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Thu, 28 Feb 2019 06:56:52 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Cc: patches@linaro.org, =?utf-8?q?Alex_Benn=C3=A9e?= , Paolo Bonzini , =?utf-8?q?Marc-Andr=C3=A9_Lureau?= , Stefan Hajnoczi , =?utf-8?q?Daniel_P_=2E_Berrang?= =?utf-8?b?w6k=?= , =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= Subject: [PATCH v2 09/11] Makefile, configure: Support building rST documentation Date: Thu, 28 Feb 2019 14:56:22 +0000 Message-Id: <20190228145624.24885-10-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190228145624.24885-1-peter.maydell@linaro.org> References: <20190228145624.24885-1-peter.maydell@linaro.org> MIME-Version: 1.0 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 --- configure | 4 ++-- Makefile | 45 ++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 44 insertions(+), 5 deletions(-) -- 2.20.1 Reviewed-by: Philippe Mathieu-Daudé Tested-by: Philippe Mathieu-Daudé diff --git a/configure b/configure index 694088a4ec9..bf6850d4bd9 100755 --- a/configure +++ b/configure @@ -4565,11 +4565,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 7fa04e08212..d6b897be0bc 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, \ @@ -633,6 +633,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 @@ -653,6 +661,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 @@ -686,7 +697,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)" @@ -837,6 +859,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","$@") @@ -865,7 +904,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