On Mon, 10 Jun 2019 at 14:45, Peter Maydell <peter.mayd...@linaro.org> wrote: > > The qemu-ga documentation is currently in qemu-ga.texi in > Texinfo format, which we present to the user as: > * a qemu-ga manpage > * a section of the main qemu-doc HTML documentation > > Convert the documentation to rST format, and present it to > the user as: > * a qemu-ga manpage > * part of the interop/ Sphinx manual > > Signed-off-by: Peter Maydell <peter.mayd...@linaro.org> > --- > This is part of my general proposals about how we should > transition away from texinfo to sphinx (written up at > https://wiki.qemu.org/Features/Documentation). It's the > first part of step 3 (convert standalone manpages), so it's > interesting as a demonstration of Sphinx generating manpages > as well as HTML. The format of the output manpage is broadly > the same, though there are a few minor differences because > rST doesn't support quite the same kinds of output. (It also > fixes a bug where the current manpage renders some text intended > to be in bold as literally "B<unix-listen>".) > > Having the infrastructure for creating a simple manpage via > Sphinx should be a useful assist for the work in step 1 of the > transition plan that involves conversion of the auto-generated > qemu-ga-ref and qemu-qmp-ref (which need to produce manpages). > > The non-manpage HTML version of the doc moves from qemu-doc.html > into docs/interop/ (its final location in the new 5-manual setup). > > Makefile | 13 ++-- > MAINTAINERS | 2 +- > docs/conf.py | 18 ++--- > docs/interop/conf.py | 7 ++ > docs/interop/index.rst | 1 + > docs/interop/qemu-ga.rst | 133 +++++++++++++++++++++++++++++++++++++ > qemu-doc.texi | 5 -- > qemu-ga.texi | 137 --------------------------------------- > 8 files changed, 161 insertions(+), 155 deletions(-) > create mode 100644 docs/interop/qemu-ga.rst > delete mode 100644 qemu-ga.texi
I just realised that I forgot to update the Makefile 'install-manual' macro to filter out the generated docs/interop/qemu-ga.8 file, so at the moment 'make install' will put a copy into /usr/local/share/doc/qemu/interop/ as well as into /usr/local/share/man/man8/. I'll fix that in v2. thanks -- PMM
