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 <stefanha@redhat.com>