[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: [Qemu-devel] [PATCH v2 00/11] Enable build and install of our rST do
From: |
Aleksandar Markovic |
Subject: |
Re: [Qemu-devel] [PATCH v2 00/11] Enable build and install of our rST docs |
Date: |
Thu, 28 Feb 2019 16:50:20 +0100 |
> Peter Maydell <address@hidden> wrote:
> This patchset enables building and installing the various rST
> docs we have started to accumulate in our docs/ directory.
For the entire series:
Acked-by: Aleksandar Markovic <address@hidden>
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/address@hidden/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
>
>
>
- [Qemu-devel] [PATCH v2 08/11] docs: Provide separate conf.py for each manual we want, (continued)
- [Qemu-devel] [PATCH v2 08/11] docs: Provide separate conf.py for each manual we want, Peter Maydell, 2019/02/28
- [Qemu-devel] [PATCH v2 07/11] docs/conf.py: Disable option warnings, Peter Maydell, 2019/02/28
- [Qemu-devel] [PATCH v2 10/11] Makefile: Abstract out "identify the pkgversion" code, Peter Maydell, 2019/02/28
- [Qemu-devel] [PATCH v2 11/11] docs/conf.py: Don't hard-code QEMU version, Peter Maydell, 2019/02/28
- [Qemu-devel] [PATCH v2 09/11] Makefile, configure: Support building rST documentation, Peter Maydell, 2019/02/28
- Re: [Qemu-devel] [PATCH v2 00/11] Enable build and install of our rST docs, no-reply, 2019/02/28
- Re: [Qemu-devel] [PATCH v2 00/11] Enable build and install of our rST docs, no-reply, 2019/02/28
- Re: [Qemu-devel] [PATCH v2 00/11] Enable build and install of our rST docs,
Aleksandar Markovic <=
- Re: [Qemu-devel] [PATCH v2 00/11] Enable build and install of our rST docs, no-reply, 2019/02/28
- Re: [Qemu-devel] [PATCH v2 00/11] Enable build and install of our rST docs, no-reply, 2019/02/28
- Re: [Qemu-devel] [PATCH v2 00/11] Enable build and install of our rST docs, no-reply, 2019/02/28