Re: [PATCH] docs: Build and install all the docs in a single manual

[Peter Maydell]

On Fri, 11 Dec 2020 at 15:48, Paolo Bonzini <pbonzini@redhat.com> wrote:
>
> On 10/12/20 21:35, 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
> >   * 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)
> >
> > Merely hiding our developer documentation from end users seems like
> > it's not enough benefit for these costs.  Combine all the
> > documentation into a single manual (the same way that the readthedocs
> > site builds it) and install the whole thing.  The previous manual
> > divisions remain as the new top level sections in the manual.
> >
> >   * The per-manual conf.py files are no longer needed
> >   * The man_pages[] specifications previously in each per-manual
> >     conf.py move to the top level conf.py
> >   * docs/meson.build logic is simplified as we now only need to run
> >     Sphinx once for the HTML and then once for the manpages5B
> >   * The old index.html.in that produced the top-level page with
> >     links to each manual is no longer needed
> >
> > Unfortunately this means that we now have to build the HTML
> > documentation into docs/manual in the build tree rather than directly
> > into docs/; otherwise it is too awkward to ensure we install only the
> > built manual and not also the dependency info, stamp file, etc.  The
> > manual still ends up in the same place in the final installed
> > directory, but anybody who was consulting documentation from within
> > the build tree will have to adjust where they're looking.
> >
> > Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
>
> Sounds good!
>
> I thought I had sent my reviewed-by in November.  If I didn't...

I think you just said it was a good idea and that the meson
stuff didn't have any obvious errors :-)

>
>
> >     man_pages = {
> > -    'interop' : {
> >           'qemu-ga.8': (have_tools ? 'man8' : ''),
> >           'qemu-ga-ref.7': 'man7',
> >           'qemu-qmp-ref.7': 'man7',
> > -    },
> > -    'tools': {
> >           'qemu-img.1': (have_tools ? 'man1' : ''),
> >           'qemu-nbd.8': (have_tools ? 'man8' : ''),
> >           'qemu-pr-helper.8': (have_tools ? 'man8' : ''),
> >           'qemu-trace-stap.1': 
> > (config_host.has_key('CONFIG_TRACE_SYSTEMTAP') ? 'man1' : ''),
> >           'virtfs-proxy-helper.1': (have_virtfs_proxy_helper ? 'man1' : ''),
> >           'virtiofsd.1': (have_virtiofsd ? 'man1' : ''),
> > -    },
> > -    'system': {
> >           'qemu.1': 'man1',
> >           'qemu-block-drivers.7': 'man7',
> >           'qemu-cpu-models.7': 'man7'
> > -    },
> >     }
>
> ... perhaps my only suggestion is to sort these by section and
> secondarily by name.  But no need to repost---or even to do it, in fact.

I guess we could as a followup. For this patch I think it's helpful
for review that it's clear that nothing changes except the removal
of the intermediate level of data structure.

> Reviewed-by: Paolo Bonzini <pbonzini@redhat.com>

Thanks!

-- PMM