On Fri, 11 Dec 2020 at 15:48, Paolo Bonzini <pbonz...@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.mayd...@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 <pbonz...@redhat.com>
Thanks!
-- PMM
