qemu-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: [RFC 0/2] Build a single Sphinx manual, not five


From: Paolo Bonzini
Subject: Re: [RFC 0/2] Build a single Sphinx manual, not five
Date: Tue, 10 Nov 2020 17:40:52 +0100
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:78.0) Gecko/20100101 Thunderbird/78.4.0

On 09/11/20 22:44, Peter Maydell wrote:
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.

No objection here of course, even for 5.2. The build system stuff seems okay too.

Paolo




reply via email to

[Prev in Thread] Current Thread [Next in Thread]