From patchwork Thu Feb 28 14:56:13 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Peter Maydell X-Patchwork-Id: 159385 Delivered-To: patches@linaro.org Received: by 2002:a02:5cc1:0:0:0:0:0 with SMTP id w62csp736065jad; Thu, 28 Feb 2019 06:56:29 -0800 (PST) X-Received: by 2002:a5d:4149:: with SMTP id c9mr6924752wrq.58.1551365789736; Thu, 28 Feb 2019 06:56:29 -0800 (PST) ARC-Seal: i=1; a=rsa-sha256; t=1551365789; cv=none; d=google.com; s=arc-20160816; b=TabvM8maeMPOA/YWivOtLmra02wjJisgDI3Cnx/FsRa6D+nVXRxb+/bJzDv1AUmNPW W/nbN2JjP65HE8snmG2g4SUd5I9TbxKTk2mhIDwZ6Er5eRuB8lcGjXC4A4QCcDMkYK6Z KdKf1SyV258gQitzaRGtmZ4YcB8rfV4bmZPLCrslOgWZqPFojZkMmHgfi4u7+UxmfEXp ARSftYjKy5o64dkuX1EpJpN+GTfo1oJ5Z+BiDJ62vrQtZrqCuS0iVWJbA5qLBzanlT50 9ScOd35/Ng/QjJmcie/iXg+Mf0tp1u8Jpn/p6uljLNDiTq9qh0D0oVAkx26B15IfxGG8 qTQg== 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=SL3kYxFkxiLezlDHKGR4O/eEHcDrAYHnTKobfm6zGnI=; b=FyYL/hkmX2PhOBb88PY268t0vAO6i95mzKlUKGZxjKjrVwJm717YsPPpTvEDYdaP3h hT/GschRC0OO8bzv0hBqOIgSQ4rzndS4zr2uPusxarT4v/TPtxuLQSPAgdyBsk5F8bc/ 3PmJt1w7sKvigbjKQyIHVlwa+glUbGOefhDdhh7lKM4zfy0kfJARnYhfuXYjfa0UQSjO ZXADrnD2dcGMZUqFljjrVy48YwXl+r/tAvBMFCtghIwv9emi8udC3PxZt2cNxxMMKtku YP3rcdI6OVwP7DlvzH+gfPcymrj/rBjAvhcwgIRktiXnwmNqOzRA8c5F8GYWLRqB8E8w Wtrw== ARC-Authentication-Results: i=1; mx.google.com; dkim=pass header.i=@linaro.org header.s=google header.b=rQx5heAi; 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 65sor3551457wmb.27.2019.02.28.06.56.29 for (Google Transport Security); Thu, 28 Feb 2019 06:56:29 -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=rQx5heAi; 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=SL3kYxFkxiLezlDHKGR4O/eEHcDrAYHnTKobfm6zGnI=; b=rQx5heAi+4JIAQovk+y2WzNJqRQ5eyGqYoCl2MHSgn/b71iSz+wIQAicsHnCPaAF/3 I9edueIAXn1PAfmNhToQcNnp4edlp0nSpaCyzQ4oGMl2FHO+kKfEViSD/9yucFSSXtEc LEqBAx9/AMmtgtu3V/uOQ3SuMkXTzsXuPPouqpBKTNq08GYTMMePr8HP1hq9Py3wqpme 4oiiQdHB+ulaFchLWuc3v/wmU0uQ35iDLZkl7ZCPbK9bm8DT3LixFG23sZ+D3Xx7TXNm MEpvDQbnGuIS6TBKRjuRi//yYpwggrpFFOQgmAqBiR63ethgYHunOwcax/hMd56U0Qcv GUzA== 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=SL3kYxFkxiLezlDHKGR4O/eEHcDrAYHnTKobfm6zGnI=; b=c+qtNCqefymELoN5m9PFEKKO9GBnIMQOgpPeIOzTtBbftaRPxt4MMl8kuzZb1xWQm6 o7PyLqdCCV/RtRLlL6OiKafCKbA8td1xXXzJkjTSi4NLH4lovAK/0rvBb2G9o2R/cpw3 toZ1+l218Ixxi39FC4bBf94Rbfuym69Kkau8MUdk1UDZ5D3dATUZe0yPgQxC7gvNAdDl S8eBqeBY3jNQ9rFMzrVf3HqhG/OCXa3MMeUhLhIXotwh2ndYP8PSZ/WXHKUWiuqmOG0a ateW9NBoQOgdnJqDrIESe0fDOhWASS3a+U6aLYIrQt7k9/4fxX0rxLWlbX/hEOqLHFET Jv8g== X-Gm-Message-State: APjAAAUacaYCqjOjiH8H3bMb02y4+DHqoCzciDiQEdCIZHhiZOxPj0QE 4RkEGlWrmddXsb2XkBecQoQGOBzr X-Google-Smtp-Source: APXvYqxiyNMnpiwifjGme3cU0lduxHLDmq4oBP06ScJL69Aw+CY6LauzaVhrI8rn+e46YROt3I5BXg== X-Received: by 2002:a7b:c146:: with SMTP id z6mr38576wmi.145.1551365789219; Thu, 28 Feb 2019 06:56:29 -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.26 (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Thu, 28 Feb 2019 06:56:28 -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 00/11] Enable build and install of our rST docs Date: Thu, 28 Feb 2019 14:56:13 +0000 Message-Id: <20190228145624.24885-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. Changes v1->v2: * Added a few missing Signed-off-by lines * Provided a proper commit message for patch 8 * patch 9: only add 'sphinxdocs' target to 'all' if BUILD_DOCS is defined (fixes building on systems without sphinx-build, which will now just not build the docs rather than barfing) All patches except 9 have been reviewed. Feedback to v1 seemed to be positive, so I propose that (assuming no further issues found in code review) we commit this series before softfreeze for the 4.1 release. All the text below here is from the v1 cover letter, for context. 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 docs: Provide 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 Acked-by: Aleksandar Markovic