From nobody Sat Oct 4 18:43:02 2025 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; Authentication-Results: mx.zohomail.com; dkim=fail; spf=pass (zoho.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=fail(p=none dis=none) header.from=linaro.org Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1551366750888983.29347523051; Thu, 28 Feb 2019 07:12:30 -0800 (PST) Received: from localhost ([127.0.0.1]:39887 helo=lists.gnu.org) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gzNMJ-00087I-M7 for importer@patchew.org; Thu, 28 Feb 2019 10:12:27 -0500 Received: from eggs.gnu.org ([209.51.188.92]:52290) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1gzN7Z-000512-4h for qemu-devel@nongnu.org; Thu, 28 Feb 2019 09:57:14 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1gzN7X-0008Ct-Op for qemu-devel@nongnu.org; Thu, 28 Feb 2019 09:57:13 -0500 Received: from mail-wm1-x344.google.com ([2a00:1450:4864:20::344]:52943) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1gzN7V-0007sE-Nk for qemu-devel@nongnu.org; Thu, 28 Feb 2019 09:57:11 -0500 Received: by mail-wm1-x344.google.com with SMTP id m1so9574099wml.2 for ; Thu, 28 Feb 2019 06:56:54 -0800 (PST) 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) 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=PiiDatsABqV/AixHs/aINYyihBKEz5l5ombUqflLMa/Qea0+Q2pjxb1mZy6MIBTFQF JJ1VNGKQKlReUCRqFdRE0c5/8XB98BuktZkePnZ3MjGjJFeW8WLg7NXrfxRJGmoE3ld1 lUnXM1qdow/cP7OkndqTYzff9CZo86k5GK5LOSOk98n9z/716dAdJUh+J5vI+88ypY4W RaxbrkMKtCVacvokA2sP7QuDcSPAyAl6v+rnRnBhC4Kx8PQcxg1V5dn2vA5Pxt/BQljH 1BRAfVrsM5Dj9HkwDccJHsFO1U0wIgl27uKlK91Cm5wTVTSC7alKsIKGmo0g0Mh7sn/c lqBA== X-Gm-Message-State: APjAAAWchR2EtySGBy7/S1Iki59Lik6huaS24VVq8PV+1uvCXUXAqpjk V34JX5q0MtiRKVRiJMaEKZ6rZ389/+Q= 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) From: Peter Maydell To: qemu-devel@nongnu.org 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 Content-Transfer-Encoding: quoted-printable X-detected-operating-system: by eggs.gnu.org: Genre and OS details not recognized. X-Received-From: 2a00:1450:4864:20::344 Subject: [Qemu-devel] [PATCH v2 09/11] 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: patches@linaro.org, =?UTF-8?q?Philippe=20Mathieu-Daud=C3=A9?= , Stefan Hajnoczi , =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= , Paolo Bonzini , =?UTF-8?q?Alex=20Benn=C3=A9e?= Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) Content-Type: text/plain; charset="utf-8" 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=C3=A9 Tested-by: Philippe Mathieu-Daud=C3=A9 --- configure | 4 ++-- Makefile | 45 ++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 44 insertions(+), 5 deletions(-) diff --git a/configure b/configure index 694088a4ec9..bf6850d4bd9 100755 --- a/configure +++ b/configure @@ -4565,11 +4565,11 @@ fi =20 # Check if tools are available to build documentation. if test "$docs" !=3D "no" ; then - if has makeinfo && has pod2man; then + if has makeinfo && has pod2man && has sphinx-build; then docs=3Dyes else if test "$docs" =3D "yes" ; then - feature_not_found "docs" "Install texinfo and Perl/perl-podlators" + feature_not_found "docs" "Install texinfo, Perl/perl-podlators and p= ython-sphinx" fi docs=3Dno fi diff --git a/Makefile b/Makefile index 7fa04e08212..d6b897be0bc 100644 --- a/Makefile +++ b/Makefile @@ -388,7 +388,7 @@ dummy :=3D $(call unnest-vars,, \ =20 include $(SRC_PATH)/tests/Makefile.include =20 -all: $(DOCS) $(TOOLS) $(HELPERS-y) recurse-all modules +all: $(DOCS) $(if $(BUILD_DOCS),sphinxdocs) $(TOOLS) $(HELPERS-y) recurse-= all modules =20 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= ,%,$@)" =20 +# 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 =3D +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=3D endif =20 -install-doc: $(DOCS) +define install-manual =3D +for d in $$(cd docs && find $1 -type d); do $(INSTALL_DIR) "$(DESTDIR)$(qe= mu_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","$@") =20 +# 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 =3D $(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 =3D $(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","$@= ") =20 @@ -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 =20 -html: qemu-doc.html docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-re= f.html +html: qemu-doc.html docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-re= f.html sphinxdocs info: qemu-doc.info docs/interop/qemu-qmp-ref.info docs/interop/qemu-ga-re= f.info pdf: qemu-doc.pdf docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.p= df txt: qemu-doc.txt docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.t= xt --=20 2.20.1