When we first converted our documentation to Sphinx, we split it into
multiple manuals (system, interop, tools, etc), which are all built
separately. The primary driver for this was wanting to be able to
avoid shipping the 'devel' manual to end-users. However, this is
working against the grain of the way Sphinx wants to be used and
causes some annoyances:
* Cross-references between documents become much harder or
possibly impossible (currently we don't even try)
* There is no single index to the whole documentation
* Within one manual there's no links or table-of-contents info
that lets you easily navigate to the others
* The devel manual doesn't get published on the QEMU website
(it would be nice to able to refer to it there)
* Common information like the QEMU license, supported platforms,
and deprecation information either gets duplicated across manuals,
split between them, or shoved into the system manual as the
closest to a generic one
Merely hiding our developer documentation from end users seems like
it's not enough benefit for these costs.
This RFC series switches over to building a single big manual,
the same way that the readthedocs version builds it.
Patch 1 in the set suppresses the warnings that would otherwise
be caused by the handful of 'orphan' rst files in the top level
directory. This is not the correct long-term thing to do with these
files -- my suggestions for most of them are in this thread:
https://lore.kernel.org/qemu-devel/CAFEAcA_ff6bRythvzJWs0McUSz3=2=1=hv9wx_btv00jpfs...@mail.gmail.com/
-- but for the purposes of this series and until somebody
cleans them up properly, this is the minimal necessary change,
because it's patch 2 that I'm really interested in opinions on.
Earlier discussion on one manual vs multiple was partly on IRC
but also in this thread:
https://lore.kernel.org/qemu-devel/CAFEAcA_4wXqGeOgsY2GbY1mk==dcz--j-jhs+odgqnohef+...@mail.gmail.com/
Incidentally, historically we did ship some internals documentation
to end users -- the old qemu-tech.texi "translator internals"
ended up in the user manual. The new 'devel' manual is a lot
bigger, of course.
If you don't want to apply this patch and build the docs to see
what the effect is, you can just look at the readthedocs output
to see what one-big-manual looks like:
https://qemu.readthedocs.io/en/latest/
Side note: it would be nice not to have to duplicate the
list of manpages in docs/conf.py and docs/meson.build. I think
if we didn't insist on only installing the manpages that apply
to the configuration we built for (ie if we installed the full
manpage docs the same way we install the full HTML docs
regardless of config) we could do that, by having Sphinx
build the manpages into a manpages/man[178]/ hierarchy and
just having meson.build do an install_subdir() on it. But
for this patchset I've retained the current behaviour.
thanks
-- PMM
Peter Maydell (2):
docs: Mark rst files in the top level directory as orphan
docs: Build and install all the docs in a single manual
docs/conf.py | 37 ++++++++++++++++++++-
docs/cpu-hotplug.rst | 2 ++
docs/devel/conf.py | 15 ---------
docs/index.html.in | 17 ----------
docs/interop/conf.py | 26 ---------------
docs/meson.build | 64 ++++++++++++++----------------------
docs/microvm.rst | 2 ++
docs/pr-manager.rst | 2 ++
docs/specs/conf.py | 16 ---------
docs/system/conf.py | 28 ----------------
docs/tools/conf.py | 33 -------------------
docs/user/conf.py | 15 ---------
docs/virtio-net-failover.rst | 2 ++
docs/virtio-pmem.rst | 1 +
14 files changed, 70 insertions(+), 190 deletions(-)
delete mode 100644 docs/devel/conf.py
delete mode 100644 docs/index.html.in
delete mode 100644 docs/interop/conf.py
delete mode 100644 docs/specs/conf.py
delete mode 100644 docs/system/conf.py
delete mode 100644 docs/tools/conf.py
delete mode 100644 docs/user/conf.py
--
2.20.1
