Re: [PATCH 0/3] convert qemu-nbd, qemu-block-drivers to rST

[Stefan Hajnoczi]

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 <address@hidden>

signature.asc
Description: PGP signature