From patchwork Tue Mar 5 17:21:36 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 159706 Delivered-To: patch@linaro.org Received: by 2002:a02:5cc1:0:0:0:0:0 with SMTP id w62csp5233944jad; Tue, 5 Mar 2019 09:36:28 -0800 (PST) X-Google-Smtp-Source: APXvYqySrESU1Wvf0XKnE1ViQIo0DLLaOQtc+B6njmrTpO8D/aBpW/PHbBYwi3CuFbOVNm3zYaDq X-Received: by 2002:a25:1955:: with SMTP id 82mr3123995ybz.76.1551807388941; Tue, 05 Mar 2019 09:36:28 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1551807388; cv=none; d=google.com; s=arc-20160816; b=RmSyMiz9PUJ1+FciVMnHRpwVIzCXVo9EhGSJh6RcyGmcGY4vafpRZ9u1V+TlaUmHVb yvXtG72CLUC/gIaYqCBM0gyCtSJa5iWX0nFqyP99B0MVTMgVB8CaHvG5OQ2tllkUyz15 WnRtUlBHguzaUiC/KoyHmL6p6HjZ2+yKTr15tEVWGSp6aItFBa1gy51iI5aKF3ODgKPm /Soi1gGH+riIGO7gn+liCXxl/8vxFtSNpPEAwnNslpg0AzXEVEnYGyKHePD2CVzT/U2+ MuvqwV1E2PJy/rCXwRWkysMYAAnAxXO/uYUZOLITaYe6mk0vyrk/Ahlhhx4G6PJ69E7r +UOQ== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=sender:errors-to:cc:list-subscribe:list-help:list-post:list-archive :list-unsubscribe:list-id:precedence:subject :content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:to:from:dkim-signature; bh=fMSJc4tOcDf53LeHi1yp309x64WCbqGkZGxQnTj7TS8=; b=yWGJXNrAqlBQPg2hqQb96B+dRW1eFesQAkbyxvQkvX9+sS66x33HzQUuNQdoYMaA0i XzXrnr3WraCU9wN8JYTEqllnYKK+kzLF7GcLFcB8oo2VJ7hiNRStIQ4ufGBiSHvrguHM Gnv6uexEkwFjc8RvVR3OScD7CZ9kp3JBTLdESIqNslkPjtxVUNgO3xJ306hR8ojNbDQm 3ebzu3Z99pG2cI9ernI2fyLHeYCDVCXFxWlkfoy8aDjX50UXWaCiieHXSjuYT1LF7NEU +QS4R17mwE4I+RfEIVju6AMRu3tePs9Nqs8tW0BHraNiJd7fSB4v207YtynJcN5K8BKT 5vPg== ARC-Authentication-Results: i=1; mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b="SlRcq5n/"; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Return-Path: Received: from lists.gnu.org (lists.gnu.org. [209.51.188.17]) by mx.google.com with ESMTPS id t185si5496588ybf.403.2019.03.05.09.36.28 for (version=TLS1 cipher=AES128-SHA bits=128/128); Tue, 05 Mar 2019 09:36:28 -0800 (PST) Received-SPF: pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; Authentication-Results: mx.google.com; dkim=fail header.i=@linaro.org header.s=google header.b="SlRcq5n/"; spf=pass (google.com: domain of qemu-devel-bounces+patch=linaro.org@nongnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom="qemu-devel-bounces+patch=linaro.org@nongnu.org"; dmarc=fail (p=NONE sp=NONE dis=NONE) header.from=linaro.org Received: from localhost ([127.0.0.1]:46660 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1h1DzQ-0004Lb-Be for patch@linaro.org; Tue, 05 Mar 2019 12:36:28 -0500 Received: from eggs.gnu.org ([209.51.188.92]:35670) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1h1DlN-0002GA-2h for qemu-devel@nongnu.org; Tue, 05 Mar 2019 12:21:58 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1h1DlL-0001AJ-PK for qemu-devel@nongnu.org; Tue, 05 Mar 2019 12:21:57 -0500 Received: from mail-wm1-x32e.google.com ([2a00:1450:4864:20::32e]:51251) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1h1DlL-00017Y-E2 for qemu-devel@nongnu.org; Tue, 05 Mar 2019 12:21:55 -0500 Received: by mail-wm1-x32e.google.com with SMTP id n19so3358618wmi.1 for ; Tue, 05 Mar 2019 09:21:55 -0800 (PST) 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=fMSJc4tOcDf53LeHi1yp309x64WCbqGkZGxQnTj7TS8=; b=SlRcq5n/3Mhnd9+iwJ2sJxvqfQq38oXieC0nXqsil5dE9bemw/krV8c8hY7QvBhZeE KAL30CTuO9gIFKIGatS/0qNBptXSDSmAzk7VLoojRwD+ycTlgEYYpuT2im+e1JFZPASm I7nGMQMLBeBBdxYHIrtbCXacoeZFwz1ifwfSGJ1rOLrhTm17TgI4et8eLwp0Gp1p1FXy wzwbQ/gk/QpygsWs4470sQ+l0eUsbxqyl6BKS3qqZOf8TbncY4D9bQgOA1bjIgRmfZD8 3uWgvZNUC+HPGWYCh9C35n322Afv/xk//l2y/fxO/g1+RApWtY6C4H8/c5t578/+a/l7 l2vQ== 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=fMSJc4tOcDf53LeHi1yp309x64WCbqGkZGxQnTj7TS8=; b=CIiGhDJcFrPUFkyj6MDXH5REvfEoGkPgK1pYOQeOs9oanopWrHWdxdzsD3ZlNORIYY qCZakAc1qOrBQWvruel2L090N8Ec85pkqfJxNbaNJzKSi+67Iyj1yZ66g4maVogBplsn nQ65O1AmKBwuK+8nwI8eA/adqfwKGxBQg5foMZO0roU00iNUVy+HvcsdiIiwKROHhNTi MX3Mfo01cV/eDQwfBk2D6kbLxdh1RaZMQTJO64dIE+L+dbK3DPMQ0T1m4SupPTKCSIeO rZmEQVQ1z3k7COnGUKNLMtmh5q4klgd5C8+Pqamx2taohhCXN7cQQ5kAjEPUGwcCfTfU x0RQ== X-Gm-Message-State: APjAAAU6CcSDP7tsv3gvTRIFQAXdbA4P6vo4u+4Hinf57ne2s9FbPLyL X2oKZeI1d4Ch4xKdDro9yGiNle1Auuk= X-Received: by 2002:a7b:c929:: with SMTP id h9mr3445896wml.106.1551806513827; Tue, 05 Mar 2019 09:21:53 -0800 (PST) Received: from orth.archaic.org.uk (orth.archaic.org.uk. [81.2.115.148]) by smtp.gmail.com with ESMTPSA id b195sm48289wmg.36.2019.03.05.09.21.52 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Tue, 05 Mar 2019 09:21:53 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Date: Tue, 5 Mar 2019 17:21:36 +0000 Message-Id: <20190305172139.32662-10-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 In-Reply-To: <20190305172139.32662-1-peter.maydell@linaro.org> References: <20190305172139.32662-1-peter.maydell@linaro.org> MIME-Version: 1.0 X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::32e Subject: [Qemu-devel] [PATCH v3 09/12] Makefile, configure: Support building rST documentation X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.21 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: =?utf-8?q?Alex_Benn=C3=A9e?= , =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Aleksandar Markovic Errors-To: qemu-devel-bounces+patch=linaro.org@nongnu.org Sender: "Qemu-devel" 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 Reviewed-by: Philippe Mathieu-Daudé Tested-by: Philippe Mathieu-Daudé Acked-by: Aleksandar Markovic Message-id: 20190228145624.24885-10-peter.maydell@linaro.org --- configure | 15 +++++++++++++-- Makefile | 45 ++++++++++++++++++++++++++++++++++++++++++--- .gitignore | 1 + 3 files changed, 56 insertions(+), 5 deletions(-) -- 2.20.1 Reviewed-by: Richard Henderson 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.*