[Qemu-devel] building rst docs with sphinx

[Peter Maydell]

I had another look this afternoon at building our rST docs
with sphinx-build. In particular, we currently have some
docs in rst format, but we're not building them into HTML
or shipping them. (Predictably, this means a few errors and
warnings have crept in...)

I had a play about with adding some makefile runes, but
I'm not sure entirely what I should be aiming for.

(1) configure: My thought is that we should just make
sphinx-build a requirement for the existing --enable-docs
switch (as texinfo and pod2man are currently). The
disadvantage is that we won't support a "build the half
of the docs you have the tools for and leave the others"
setup. The advantage, which I think is significant, is that
distros will naturally be directed to the missing build
dependency (either they're building with --enable-docs
and will get the configure message, or they aren't and
then their build will fail later because of missing docs
files when they try to put the built files into the package).

(2) What do we actually want to ship?
That is, what do we want 'make install-doc' to copy into
the installation directory?
https://wiki.qemu.org/Features/Documentation
has a good suggested breakdown of docs for where we
eventually want to be. I think we probably don't want
to install the "developer's guide" (docs/devel) on
end-user systems. The others are presumably OK.
Currently, we seem to only install manpages and a
few other things in the 'install-doc' makefile target
(we don't install a bunch of plain-text user-facing
docs) so this would be a significant expansion.

(3) Indexes, table-of-contents pages, etc
Are we aiming to ship these?
I think that we probably want to have what from
Sphinx's point of view are multiple separate documents,
so that they each get their own ToC and index. This
means we can for instance ship the ToC/index for
the user docs but not have it contain index entries
for developer docs.

Overall what I'm hoping for is to be able to get some
basic structure/building commands into master so we
have a framework and something we can iterate on to
move forward.

thanks
-- PMM