On Thu, Jan 16, 2020 at 02:15:08PM +0000, Peter Maydell wrote: > This patchset converts the qemu-nbd and qemu-block-drivers > documentation from texinfo to rST. For both of these, > currently the documentation is in texinfo, which we present > to the user as: > * a manpage > * a section of the qemu-doc HTML documentation > > The conversion results in the docs being in rST format, > presented to the user as: > * a manpage > * a section of one of the Sphinx manuals (interop/ > for qemu-nbd, and system/ for qemu-block-drivers) > > The first patch is the same as the "qemu-nbd: Convert invocation > documentation to rST" patch I sent a couple of days ago, except that > I have folded some of the long Makefile lines as Eric suggested. > > Patch 2 creates the new 'system' manual; this has always > been in our plan for the docs as described in > https://wiki.qemu.org/Features/Documentation > but this is the first point where we have some actual > content for it. > > Patch 3 converts the qemu-block-drivers docs/manpage. As noted in > the commit message for that patch, this requires dropping a minor > cross-reference from the '-cdrom' option documentation to this > (because they're no longer in the same big texinfo document). There > is also a slightly ugly compromise in the manpage output in order to > provide better HTML output, which is forced on us by limitations in > Sphinx. > > Apologies for the size of patch 3, but a single big-bang conversion > of this 1000 page document seemed better than artificially trying to > split it somehow, since only one of the two formats can actually > produce the manpage at once. > > PS: the old docs/qemu-block-drivers.texi is not covered by > any MAINTAINERS section, so I haven't added the new > docs/system/qemu-block-drivers.rst anywhere either. > Perhaps it should go in the "Block layer core" section? > > thanks > -- PMM > > Peter Maydell (3): > qemu-nbd: Convert invocation documentation to rST > docs: Create stub system manual > qemu-block-drivers: Convert to rST > > Makefile | 37 +- > MAINTAINERS | 1 + > docs/interop/conf.py | 4 +- > docs/interop/index.rst | 1 + > docs/interop/qemu-nbd.rst | 263 +++++++ > docs/interop/qemu-option-trace.rst.inc | 30 + > docs/qemu-block-drivers.texi | 889 ---------------------- > docs/{interop => system}/conf.py | 10 +- > docs/system/index.rst | 17 + > docs/system/qemu-block-drivers.rst | 985 +++++++++++++++++++++++++ > qemu-doc.texi | 18 - > qemu-nbd.texi | 214 ------ > qemu-option-trace.texi | 4 + > qemu-options.hx | 2 +- > 14 files changed, 1336 insertions(+), 1139 deletions(-) > create mode 100644 docs/interop/qemu-nbd.rst > create mode 100644 docs/interop/qemu-option-trace.rst.inc > delete mode 100644 docs/qemu-block-drivers.texi > copy docs/{interop => system}/conf.py (64%) > create mode 100644 docs/system/index.rst > create mode 100644 docs/system/qemu-block-drivers.rst > delete mode 100644 qemu-nbd.texi > > -- > 2.20.1 > >
Acked-by: Stefan Hajnoczi <stefa...@redhat.com>
signature.asc
Description: PGP signature
