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

[Paolo Bonzini <pbonzini@redhat.com>]

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