Re: [Qemu-devel] Sphinx and docs/index.rst: dead code?

[Peter Maydell <peter.maydell@linaro.org>]

On Thu, 25 Jul 2019 at 00:22, John Snow <jsnow@redhat.com> wrote:
>
> Does anything actually use this file? It doesn't appear to be used for
> generating the HTML manuals.

It's there for if you want to do a "build all the manuals into
a single document" -- see the comments at the top of docs/conf.py.
Basically this is there because for QEMU's own purposes we want
to build several separate manuals (devel, interop, etc) so we
can install for the user only the ones that are user-facing
(ie "not devel"). But it seemed to me at the time to be worth
also supporting the "build a full thing" for the benefit of
sites like readthedocs. Currently the only way to use it is
if you hand-run an appropriate sphinx-build command.
(The fact that we will need to do some running of other
commands to autogenerate .rst input from .hx files might mean
that it's not really possible to support this sort of "third party
site" docs setup in the end; but for the moment we retain the
option to do this.)

Doing a top-level build will also complain about a couple
random .rst files in docs/ not being in the toc tree --
we need to fix this at some point anyway by putting that
documentation into its proper place in the manual set.

> It looks like we might use it for latex, man and texinfo output from
> sphinx judging by docs/conf.py, but I don't think we actually use sphinx
> to generate such output, so I think this is all dead code.

We will generate the manpage output in the same way we do
HTML, by invoking sphinx-build on the different manual
directories -- nothing in-tree does this today but this
patch:
https://patchew.org/QEMU/20190618104718.25433-1-peter.maydell@linaro.org/
does the conversion of the qemu-ga docs/manpage and should
be ready to go in once 4.1 is out the door.

thanks
-- PMM