[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH v2 0/8] qemu-img, qemu-trace-stap, virtfs-proxy-helper: convert t
From: |
Peter Maydell |
Subject: |
[PATCH v2 0/8] qemu-img, qemu-trace-stap, virtfs-proxy-helper: convert to rST |
Date: |
Fri, 24 Jan 2020 16:25:58 +0000 |
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
- [PATCH v2 0/8] qemu-img, qemu-trace-stap, virtfs-proxy-helper: convert to rST,
Peter Maydell <=
- [PATCH v2 1/8] Makefile: Ensure we don't run Sphinx in parallel for manpages, Peter Maydell, 2020/01/24
- [PATCH v2 2/8] hxtool: Support SRST/ERST directives, Peter Maydell, 2020/01/24
- [PATCH v2 3/8] docs/sphinx: Add new hxtool Sphinx extension, Peter Maydell, 2020/01/24
- [PATCH v2 4/8] qemu-img-cmds.hx: Add rST documentation fragments, Peter Maydell, 2020/01/24
- [PATCH v2 6/8] qemu-img-cmds.hx: Remove texinfo document fragments, Peter Maydell, 2020/01/24