[Qemu-devel] [PATCH 00/11] Enable build and install of our rST docs

[Peter Maydell]

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/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
  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