On Thu, 25 Jul 2019 at 00:22, John Snow <js...@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.mayd...@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
