From patchwork Fri Feb 1 14:50:24 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 157228 Delivered-To: patches@linaro.org Received: by 2002:a02:48:0:0:0:0:0 with SMTP id 69csp527065jaa; Fri, 1 Feb 2019 06:50:39 -0800 (PST) X-Received: by 2002:adf:d4c9:: with SMTP id w9mr38929328wrk.119.1549032638908; Fri, 01 Feb 2019 06:50:38 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1549032638; cv=none; d=google.com; s=arc-20160816; b=C0IJSBFmCnp1cbhN4UO0LuuhdLqrYi/PgcE6yqcnW2GGQXNTxb8RBEHQLRxzjGR+y9 vwFX3O7oXf9AI/O1xJeBSuPOHRRnYqzEXpMP/mGHPZABWTG1ohnIM7VHv0sgtVfYcPs8 f+B3RV4Xc6UP82XV94/GuJEnWF+NV7yHghpD13X+TdMcPZMCWORhaSiuKIN9k7YkzaAz iKU162Z5angzOqivx1xKAs+nDmALrrXwWV1DPRZYwx29pO48ksdtZj3ss+syRH1FjYbl she27uqSRtOi1R3HJ806G14a4KlxHo6L0lgp+LSlHDPdlk0aU5qf4N+DYUX+Hul2PggY 3F6A== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:dkim-signature; bh=CHcw0XBIs2Xx0OaVZwj0JLgva43G8R7t5kSx4bcfuo0=; b=HhpBnL2cNb7bnkqZKixmGhcGpCW08+cdLNFgibx+C1cs1jjeTsmwb95WhXhbtoRyHA P6x26aqJLpM93v5nE36cfLj15HubVY6yGsK7R6XYPCgCR+PP9Z7C5yI8dqOkaJbiVeLG PnnEGc0Tt0oMgbxeJhsAu6XySTbvkkx5SqmzxCkcLvqG/PiEvwy0Qq207C7GRJSnsoil tPDl8qMcouJURtP4xopVjiHV5+gFGtuR5gNgUi1vodf5w38gvMc6i2AVYT89GnHzFcMH lcjZq3WoGZM+WNK8PPJ7yvZzhPIMbZG8T2HMUqBlsfabSLD50O1UwLMKR2znJCzmYoGj hYMw== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=jIFWwddj; 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 s10sor5916137wrm.5.2019.02.01.06.50.38 for (Google Transport Security); Fri, 01 Feb 2019 06:50:38 -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=jIFWwddj; 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:mime-version :content-transfer-encoding; bh=CHcw0XBIs2Xx0OaVZwj0JLgva43G8R7t5kSx4bcfuo0=; b=jIFWwddjEQimKu8nv1DcjtLDyoprjbdRJ0WJ2c2tf8h1wc3V0l0Gxn5ozaZ9wSkR6v w6PTqzjqk33p8Cw6ro/hiGk9Ugcan1qDazjY6OtLHHYjbWrcVy845z9CyB4DX+gRsLaJ MAmKBJzCR551SXjvvnhiW2s+cWZe734PmwF14= 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:mime-version :content-transfer-encoding; bh=CHcw0XBIs2Xx0OaVZwj0JLgva43G8R7t5kSx4bcfuo0=; b=C7xJPrT3gTf1/IS/3zFbJr9nT9k0X8OlUFxP+MVtOOr7ZnGdpI0ZPpm2Qy+iuD0Dhk Wursw+ktuKfqTKB2mw2p2kW11wiXMhgiJ8p+39U9d6GTYt8se9Z6xG63PuPW3Tmx2fXS qD8QioF7044wwrVOswVU3j3iiU0Cda6LcFMTTeUgMKD4wUrbRSF3yDN7shqGr5vroQWv XJU9MGkGdc3CcSS9cQmsbf+dGl3mibopk4KU2+wra0vslW1eUqo4GsqxfHYdKOBdLXkr eNq/Z86JwAxzQF/wysMMQacaGiJ44nGNdr2MPFlcCPM76ReDrhyLvX0vUMQHXr8ik/Uf IGuA== X-Gm-Message-State: AHQUAuY+3vOntt1nOIMKdvCpbnPen2vHfB434xh0JlYm7bvwHirsKZ0i CW17ZZv38JnrZrd73eeao+ZxUutI X-Google-Smtp-Source: AHgI3IZYny8IClsN++Jy/UpbbPhEiBsNe6pqkfDjkDXsTOIS8DKZDTjTfLb5vtgIGCdxrJ5k6Rt6uA== X-Received: by 2002:adf:f6c9:: with SMTP id y9mr1722879wrp.138.1549032638237; Fri, 01 Feb 2019 06:50:38 -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 c21sm12988975wre.71.2019.02.01.06.50.36 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Fri, 01 Feb 2019 06:50:37 -0800 (PST) From: Peter Maydell To: qemu-devel@nongnu.org Cc: patches@linaro.org, Stefan Hajnoczi , Paolo Bonzini , =?utf-8?q?Daniel_P_=2E_Berrang=C3=A9?= , =?utf-8?q?Marc-Andr=C3=A9_Lureau?= , =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= Subject: [PATCH 00/11] Enable build and install of our rST docs Date: Fri, 1 Feb 2019 14:50:24 +0000 Message-Id: <20190201145035.22739-1-peter.maydell@linaro.org> X-Mailer: git-send-email 2.20.1 MIME-Version: 1.0 This patchset enables building and installing the various rST docs we have started to accumulate in our docs/ directory. It does this using Sphinx (which is the docs tooling that the Linux kernel uses). The series is not trying to take us in one giant leap to a brave new Sphinx-powered world -- it is simply setting up a framework so that we are at least building and shipping these documents and can gradually migrate other parts of our documentation to it. The approach I've used here is that we will have multiple "manuals", as proposed by Paolo here: https://wiki.qemu.org/Features/Documentation For the moment I've only created 'interop' and 'devel' as we don't yet have any rST files for 'user', 'system' or 'specs'. One slightly awkward mismatch between how Sphinx naturally wants to work and our requirements is that when Sphinx generates a documentation set all in one go it creates hyperlinks between all the docs, they all appear in a single top level table of contents, and so on. But for QEMU's docs we don't want to ship the "devel" manual to end-users. I've taken an approach suggested to me on sphinx-users (https://www.mail-archive.com/sphinx-users@googlegroups.com/msg03224.html) where we run Sphinx once per manual, and treat them as entirely separate documents. The config/tooling in this patchset also supports building everything in a single run, for compatibility with third-party docs sites like readthedocs.org. To see the results: What you get in the docs/ subdir of your build directory when you do a local build: http://people.linaro.org/~peter.maydell/build-dir-docs/ (follow the links to 'devel' and 'interop' for the two manuals) What we'll ship in 'make install' in /usr/local/share/doc/qemu/ http://people.linaro.org/~peter.maydell/installed-docs/ (should be same as the build dir except we don't ship 'devel') What you get with a standalone single-run docs build: http://people.linaro.org/~peter.maydell/standalone-docs/index.html These use the default 'alabaster' theme from Sphinx. I also experimented with the 'read_the_docs' theme, which I do think looks nicer. Unfortunately it also requires the docs we install to include about 3MB of TrueType font files per manual, which is awkward licensing-wise as the TTFs are under the Open Font License and it's not completely clear to me that it's OK to ship those to use with a doc file that is GPLed. Alabaster doesn't ship fonts, which sidesteps both those problems. Other notes: * this does not build the two .rst files that are directly in docs/ (cpu-hotplug.rst and pr-manager.rst) -- we should move these to whichever of the five manuals is the best place * I do have some prototype patches which integrate the kernel's kerneldoc Sphinx extension to parse doc comments in source code. I haven't included them here because I think the 'devel' manual is the lowest priority of the five. They might be useful if we want to try things like building documentation of supported machine models from in-code comments/etc, though. * as noted in a previous email thread, the configure changes now mean that building docs depends on build-sphinx being available, so this is a new build-dep for --enable-docs. thanks -- PMM Peter Maydell (11): docs/cpu-hotplug.rst: Fix rST markup issues docs: Convert memory.txt to rst format docs: Commit initial files from sphinx-quickstart docs/conf.py: Disable unused _static directory docs/conf.py: Configure the 'alabaster' theme docs/conf.py: Don't include rST sources in HTML build docs/conf.py: Disable option warnings Separate conf.py for each manual we want Makefile, configure: Support building rST documentation Makefile: Abstract out "identify the pkgversion" code docs/conf.py: Don't hard-code QEMU version configure | 4 +- Makefile | 78 +++++++--- docs/conf.py | 215 ++++++++++++++++++++++++++ docs/cpu-hotplug.rst | 2 +- docs/devel/conf.py | 15 ++ docs/devel/index.rst | 21 +++ docs/devel/{memory.txt => memory.rst} | 128 ++++++++------- docs/index.rst | 15 ++ docs/interop/conf.py | 15 ++ docs/interop/index.rst | 18 +++ 10 files changed, 430 insertions(+), 81 deletions(-) create mode 100644 docs/conf.py create mode 100644 docs/devel/conf.py create mode 100644 docs/devel/index.rst rename docs/devel/{memory.txt => memory.rst} (85%) create mode 100644 docs/index.rst create mode 100644 docs/interop/conf.py create mode 100644 docs/interop/index.rst -- 2.20.1