From nobody Mon Feb 9 23:02:07 2026 Delivered-To: importer@patchew.org Received-SPF: pass (zohomail.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 (zohomail.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=redhat.com Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1580239477268873.937040032266; Tue, 28 Jan 2020 11:24:37 -0800 (PST) Received: from localhost ([::1]:36032 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iwWTU-0005EJ-0n for importer@patchew.org; Tue, 28 Jan 2020 14:24:36 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:37942) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1iwV8N-0004v0-AQ for qemu-devel@nongnu.org; Tue, 28 Jan 2020 12:58:45 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1iwV8L-00015y-15 for qemu-devel@nongnu.org; Tue, 28 Jan 2020 12:58:43 -0500 Received: from mail-wr1-x435.google.com ([2a00:1450:4864:20::435]:45425) by eggs.gnu.org with esmtps (TLS1.0:RSA_AES_128_CBC_SHA1:16) (Exim 4.71) (envelope-from ) id 1iwV8K-00012k-Md for qemu-devel@nongnu.org; Tue, 28 Jan 2020 12:58:40 -0500 Received: by mail-wr1-x435.google.com with SMTP id a6so2512841wrx.12 for ; Tue, 28 Jan 2020 09:58:40 -0800 (PST) Received: from localhost.localdomain (93-36-56-206.ip58.fastwebnet.it. [93.36.56.206]) by smtp.gmail.com with ESMTPSA id o4sm27046968wrx.25.2020.01.28.09.58.36 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Tue, 28 Jan 2020 09:58:38 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20161025; h=sender:from:to:cc:subject:date:message-id:in-reply-to:references :mime-version:content-transfer-encoding; bh=qDLCPnXjd/iVjHweWz1qT0ww0/vBO7l7RrD/8qo57Hk=; b=OcBh34H4WJ+GgiSNW84/wAjA2FRc5At4htUh/r8kv86N18t5tiwxr8j+m6iiQNKP9s vsP/df5YdfyrzLoBskjJyzcVIqN0JawMRlP9yOD0N2+2aTGVAkF6WX1Fv6koQ/u4Szw8 K1x3q5rIOw77UrARjcIEVZKyshf0J+dgFYnoGxx35Q0kTaOiEkYklgMF3wo0PeJWYLRM 21TD6RHe6BD4rWxQvZMC/9thOQ9zo+wza62VM+Ahis1H79DuekPOj0XaHn3dQuFS9VIe 768SpMK+xS5wrjiRu7j8ey/ICctmVbMHsmx1AxyjRh6Ddx8BDITzRRxIjfE8f4P7W4ce /aiA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20161025; h=x-gm-message-state:sender:from:to:cc:subject:date:message-id :in-reply-to:references:mime-version:content-transfer-encoding; bh=qDLCPnXjd/iVjHweWz1qT0ww0/vBO7l7RrD/8qo57Hk=; b=p79f6WkBylElHoNjK070QBP1ke2OOUpH7W/eCc7yABOxy+qO9ff7De709SGM7JUVw4 B8vc3SLe2mON7EeGJkfU5L0Qbgqt3heT+jTc222KEEYgO4Ltnf0UVjYuPFnKbq73qZGE Qpiqj7EoU9yar/tUrME59GPFoBSniCgfbcrIv9DWCmtu/vpPz+bpBWWJMEPdSbeNTrYZ jk9VpxCGuDxAYH8Hn3jEtH2AP/JXnQxSq3QE9DE3bpSJ1D733atb7M9PEOkeM42fjId6 toSmbGxmIV9PKkJrlyoUY6YZcJL9VfY479FThuZo6sB3jnpULgGLhxP6blpnBIDX21NM YPSQ== X-Gm-Message-State: APjAAAXzQnEvQx4qRCVg/omsn1w2/SxBjmjtN2B842T8VifgDLrP2POM Pl6i72VtDGwnj+noFVTXmK3XYP3V X-Google-Smtp-Source: APXvYqx5E6ZFrvT5cL/i3rWArR00ORfhLBw1L2T/G3BVZIoiPmm6PnY5Z/mWGERvW50eGU9de1FQ+w== X-Received: by 2002:a5d:608a:: with SMTP id w10mr28447293wrt.136.1580234319453; Tue, 28 Jan 2020 09:58:39 -0800 (PST) From: Paolo Bonzini To: qemu-devel@nongnu.org Subject: [PATCH 123/142] meson: sphinx-build Date: Tue, 28 Jan 2020 18:53:23 +0100 Message-Id: <20200128175342.9066-124-pbonzini@redhat.com> X-Mailer: git-send-email 2.21.0 In-Reply-To: <20200128175342.9066-1-pbonzini@redhat.com> References: <20200128175342.9066-1-pbonzini@redhat.com> MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" 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::435 X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: =?UTF-8?q?Marc-Andr=C3=A9=20Lureau?= Errors-To: qemu-devel-bounces+importer=patchew.org@nongnu.org Sender: "Qemu-devel" X-ZohoMail-DKIM: fail (Header signature does not verify) From: Marc-Andr=C3=A9 Lureau Signed-off-by: Marc-Andr=C3=A9 Lureau --- Makefile | 67 ++---------------------------------- docs/meson.build | 88 ++++++++++++++++++++++++++++++++++++++++++++++++ meson.build | 2 ++ 3 files changed, 92 insertions(+), 65 deletions(-) create mode 100644 docs/meson.build diff --git a/Makefile b/Makefile index 898aa81232..c8681ddec7 100644 --- a/Makefile +++ b/Makefile @@ -121,19 +121,8 @@ $(call set-vpath, $(SRC_PATH)) =20 LIBS+=3D-lz $(LIBS_TOOLS) =20 -# Sphinx does not allow building manuals into the same directory as -# the source files, so if we're doing an in-tree QEMU build we must -# build the manuals into a subdirectory (and then install them from -# there for 'make install'). For an out-of-tree build we can just -# use the docs/ subdirectory in the build tree as normal. -ifeq ($(realpath $(SRC_PATH)),$(realpath .)) -MANUAL_BUILDDIR :=3D docs/built -else -MANUAL_BUILDDIR :=3D docs -endif - ifdef BUILD_DOCS -DOCS=3Dqemu-doc.html qemu-doc.txt qemu.1 qemu-img.1 qemu-nbd.8 $(MANUAL_BU= ILDDIR)/interop/qemu-ga.8 +DOCS=3Dqemu-doc.html qemu-doc.txt qemu.1 qemu-img.1 qemu-nbd.8 DOCS+=3Ddocs/interop/qemu-qmp-ref.html docs/interop/qemu-qmp-ref.txt docs/= interop/qemu-qmp-ref.7 DOCS+=3Ddocs/interop/qemu-ga-ref.html docs/interop/qemu-ga-ref.txt docs/in= terop/qemu-ga-ref.7 DOCS+=3Ddocs/qemu-block-drivers.7 @@ -231,11 +220,6 @@ dist: qemu-$(VERSION).tar.bz2 qemu-%.tar.bz2: $(SRC_PATH)/scripts/make-release "$(SRC_PATH)" "$(patsubst qemu-%.tar.bz2= ,%,$@)" =20 -define clean-manual =3D -rm -rf $(MANUAL_BUILDDIR)/$1/_static -rm -f $(MANUAL_BUILDDIR)/$1/objects.inv $(MANUAL_BUILDDIR)/$1/searchindex.= js $(MANUAL_BUILDDIR)/$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 tests/tcg/config-*.mak @@ -257,10 +241,6 @@ 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 -rf .doctrees - $(call clean-manual,devel) - $(call clean-manual,interop) - $(call clean-manual,specs) rm -Rf .sdk if test -f dtc/version_gen.h; then $(MAKE) $(DTC_MAKE_ARGS) clean; fi =20 @@ -300,22 +280,7 @@ BLOBS=3D DESCS=3D endif =20 -# Note that we manually filter-out the non-Sphinx documentation which -# is currently built into the docs/interop directory in the build tree, -# and also any sphinx-built manpages. -define install-manual =3D -for d in $$(cd $(MANUAL_BUILDDIR) && find $1 -type d); do $(INSTALL_DIR) "= $(DESTDIR)$(qemu_docdir)/$$d"; done -for f in $$(cd $(MANUAL_BUILDDIR) && find $1 -type f -a '!' '(' -name '*.[= 0-9]' -o -name 'qemu-*-qapi.*' -o -name 'qemu-*-ref.*' ')' ); do $(INSTALL_= DATA) "$(MANUAL_BUILDDIR)/$$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) - $(call install-manual,specs) - -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)" @@ -337,7 +302,6 @@ ifdef CONFIG_TRACE_SYSTEMTAP $(INSTALL_DATA) scripts/qemu-trace-stap.1 "$(DESTDIR)$(mandir)/man1" endif ifeq ($(CONFIG_GUEST_AGENT),y) - $(INSTALL_DATA) $(MANUAL_BUILDDIR)/interop/qemu-ga.8 "$(DESTDIR)$(mandir)= /man8" $(INSTALL_DATA) docs/interop/qemu-ga-ref.html "$(DESTDIR)$(qemu_docdir)" $(INSTALL_DATA) docs/interop/qemu-ga-ref.txt "$(DESTDIR)$(qemu_docdir)" $(INSTALL_DATA) docs/interop/qemu-ga-ref.7 "$(DESTDIR)$(mandir)/man7" @@ -435,33 +399,6 @@ docs/version.texi: $(SRC_PATH)/VERSION config-host.mak %.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: $(MANUAL_BUILDDIR)/devel/index.html $(MANUAL_BUILDDIR)/interop= /index.html $(MANUAL_BUILDDIR)/specs/index.html - -# Canned command to build a single manual -# Arguments: $1 =3D manual name, $2 =3D Sphinx builder ('html' or 'man') -# Note the use of different doctree for each (manual, builder) tuple; -# this works around Sphinx not handling parallel invocation on -# a single doctree: https://github.com/sphinx-doc/sphinx/issues/2946 -build-manual =3D $(call quiet-command,CONFDIR=3D"$(qemu_confdir)" sphinx-b= uild $(if $(V),,-q) -W -b $2 -D version=3D$(VERSION) -D release=3D"$(FULL_V= ERSION)" -d .doctrees/$1-$2 $(SRC_PATH)/docs/$1 $(MANUAL_BUILDDIR)/$1 ,"SPH= INX","$(MANUAL_BUILDDIR)/$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 - -$(MANUAL_BUILDDIR)/devel/index.html: $(call manual-deps,devel) - $(call build-manual,devel,html) - -$(MANUAL_BUILDDIR)/interop/index.html: $(call manual-deps,interop) - $(call build-manual,interop,html) - -$(MANUAL_BUILDDIR)/specs/index.html: $(call manual-deps,specs) - $(call build-manual,specs,html) - -$(MANUAL_BUILDDIR)/interop/qemu-ga.8: $(call manual-deps,interop) - $(call build-manual,interop,man) - docs/interop/qemu-qmp-qapi.texi: qapi/qapi-doc.texi @cp -p $< $@ =20 diff --git a/docs/meson.build b/docs/meson.build new file mode 100644 index 0000000000..0f86c0b522 --- /dev/null +++ b/docs/meson.build @@ -0,0 +1,88 @@ +sphinx =3D find_program('sphinx-build', required: build_docs) + +SPHINX_ARGS =3D [sphinx, '-W', '-q', '-d', '@PRIVATE_DIR@', + '-Dversion=3D' + config_host['VERSION'], + '-Drelease=3D' + config_host['PKGVERSION']] + +if sphinx.found() + devel_rst =3D [ + 'devel/decodetree.rst', + 'devel/index.rst', + 'devel/kconfig.rst', + 'devel/loads-stores.rst', + 'devel/memory.rst', + 'devel/migration.rst', + 'devel/secure-coding-practices.rst', + 'devel/stable-process.rst', + 'devel/tcg.rst', + 'devel/testing.rst', + ] + devel =3D custom_target('sphinx-devel', + build_by_default: build_docs, + input: devel_rst, + depend_files: [files('conf.py', 'devel/conf.py')], + output: 'devel', + command: [SPHINX_ARGS, '-b', 'html', + meson.current_source_dir() / 'devel', + '@OUTPUT@', + ]) + + interop_rst =3D [ + 'interop/bitmaps.rst', + 'interop/index.rst', + 'interop/live-block-operations.rst', + 'interop/qemu-ga.rst', + 'interop/pr-helper.rst', + 'interop/vhost-user-gpu.rst', + 'interop/vhost-user.rst', + ] + interop_man_pages =3D [] + if 'CONFIG_GUEST_AGENT' in config_host + interop_man_pages +=3D ['qemu-ga.8'] + endif + interop =3D custom_target('sphinx-interop', + build_by_default: build_docs, + input: interop_rst, + depend_files: [files('conf.py', 'interop/conf.py')], + output: 'interop', + command: [SPHINX_ARGS, '-b', 'html', + meson.current_source_dir() / 'interop', + '@OUTPUT@', + ]) + interop_man =3D custom_target('sphinx-interop-man', + build_by_default: build_docs, + input: interop_rst, + depend_files: [files('conf.py', 'interop/conf.py')], + output: interop_man_pages, + install_dir: get_option('mandir') / 'man8', + command: [SPHINX_ARGS, '-b', 'man', + meson.current_source_dir() / 'interop', + '@OUTPUT@', + ]) + if build_docs + install_subdir(meson.current_build_dir() / 'interop', + install_dir: config_host['qemu_docdir'], + exclude_directories: '.doctrees') + endif + + specs_rst =3D [ + 'specs/index.rst', + 'specs/ppc-spapr-xive.rst', + 'specs/ppc-xive.rst', + ] + specs =3D custom_target('sphinx-specs', + input: specs_rst, + depend_files: [files('conf.py', 'specs/conf.py')], + output: 'specs', + command: [SPHINX_ARGS, '-b', 'html', + meson.current_source_dir() / 'specs', + '@OUTPUT@', + ]) + if build_docs + install_subdir(meson.current_build_dir() / 'specs', + install_dir: config_host['qemu_docdir'], + exclude_directories: '.doctrees') + endif + + sphinxdocs =3D alias_target('sphinxdocs', devel, interop, interop_man, s= pecs) +endif diff --git a/meson.build b/meson.build index 0dd6d9f723..04068fd765 100644 --- a/meson.build +++ b/meson.build @@ -7,6 +7,7 @@ config_host =3D kconfig.load(meson.current_build_dir() / 'c= onfig-host.mak') config_all_disas =3D kconfig.load(meson.current_build_dir() / 'config-all-= disas.mak') =20 enable_modules =3D 'CONFIG_MODULES' in config_host +build_docs =3D 'BUILD_DOCS' in config_host =20 add_project_arguments(config_host['CFLAGS'].split(), language: ['c', 'objc']) @@ -949,3 +950,4 @@ if have_tools endif =20 subdir('pc-bios') +subdir('docs') --=20 2.21.0