[PATCH v2 0/8] qemu-img, qemu-trace-stap, virtfs-proxy-helper: convert to rST

[Peter Maydell]

This patchset converts the following documentation to rST format:
 * qemu-img
 * qemu-trace-stap
 * virtfs-proxy-helper

(That means everything in step 3 in the plan:
https://wiki.qemu.org/Features/Documentation#3:_Convert_things_which_are_mostly_standalone_manpages
will be done except for qemu-cpu-models.texi. That
should be a straightforward conversion but I haven't
touched it yet because I know there's an on-list patch
that updates the texi and wanted to avoid a conflict.)

The patchset includes a new Sphinx extension which handles parsing
the .hx files which provide documentation fragments for the qemu-img
manual.

Changes from v1 to v2:
 * rebased on master, since the qemu-nbd conversion has now
   gone in
 * the patches at the end to convert qemu-trace-stap and
   virtfs-proxy-helper are new
 * new patch at the start of the series which fixes a
   bug in our makefiles where we could try to invoke
   Sphinx twice in parallel on the same doctree (which
   causes it to crash, as well as being unnecessary work)
 * fixed the import line for ExtensionError, so this
   should now work with Sphinx 1.8

I've assigned manpages to interop/ or system/ according
to the structure set out in the wiki page above. We should
have a discussion about whether some of these should go
in a new tools/ manual or not (I'll start a separate
thread for that), but it's easy enough to move them
later if we need to.

The general approach follows the outline in the email I
sent the other day:
https://lists.gnu.org/archive/html/qemu-devel/2020-01/msg03786.html

The new Sphinx extension implements the hxtool-doc::
directive, which indicates where the assembled rST
document fragments should be inserted into the manual.
qemu-img-cmds.hx doesn't use the DEFHEADING or ARCHHEADING
directives, but the extension implements them (tested
with some local modifications to the .hx file to check
that they do the right thing).

As noted in the commit message for the qemu-img.texi conversion,
I have not attempted to tackle any of the muddle in the
current documentation structure or the repetition between
the manual document, the fragments in the .hx file and
the C code; this is a "simplest thing that works"
like-for-like conversion.

Another deliberate omission is that I have not attempted
to get links between our various Sphinx manuals (system,
interop, etc) working yet, as this is not totally trivial
and the odd minor missed hyperlink doesn't seem to me
to be a deal-breaker.

Sorry about the size of the main 'convert qemu-img'
patch, but it's unavoidable when converting a big
document between formats.

thanks
-- PMM

Peter Maydell (8):
  Makefile: Ensure we don't run Sphinx in parallel for manpages
  hxtool: Support SRST/ERST directives
  docs/sphinx: Add new hxtool Sphinx extension
  qemu-img-cmds.hx: Add rST documentation fragments
  qemu-img: Convert invocation documentation to rST
  qemu-img-cmds.hx: Remove texinfo document fragments
  scripts/qemu-trace-stap: Convert documentation to rST
  virtfs-proxy-helper: Convert documentation to rST

 Makefile                             |  46 +-
 MAINTAINERS                          |   3 +
 docs/conf.py                         |   3 +-
 docs/interop/conf.py                 |   9 +-
 docs/interop/index.rst               |   3 +
 docs/interop/qemu-img.rst            | 822 +++++++++++++++++++++++++++
 docs/interop/qemu-trace-stap.rst     | 124 ++++
 docs/interop/virtfs-proxy-helper.rst |  72 +++
 docs/sphinx/hxtool.py                | 210 +++++++
 fsdev/virtfs-proxy-helper.texi       |  63 --
 qemu-doc.texi                        |  10 +-
 qemu-img-cmds.hx                     |  99 ++--
 qemu-img.texi                        | 795 --------------------------
 rules.mak                            |  36 ++
 scripts/hxtool                       |  33 +-
 scripts/qemu-trace-stap.texi         | 140 -----
 16 files changed, 1383 insertions(+), 1085 deletions(-)
 create mode 100644 docs/interop/qemu-img.rst
 create mode 100644 docs/interop/qemu-trace-stap.rst
 create mode 100644 docs/interop/virtfs-proxy-helper.rst
 create mode 100644 docs/sphinx/hxtool.py
 delete mode 100644 fsdev/virtfs-proxy-helper.texi
 delete mode 100644 qemu-img.texi
 delete mode 100644 scripts/qemu-trace-stap.texi

-- 
2.20.1