mirror of
https://github.com/izzy2lost/xemu.git
synced 2026-07-06 00:20:22 -07:00
qemu-block-drivers: Convert to rST
The qemu-block-drivers documentation is currently in docs/qemu-block-drivers.texi in Texinfo format, which we present to the user as: * a qemu-block-drivers manpage * a section of the main qemu-doc HTML documentation Convert the documentation to rST format, and present it to the user as: * a qemu-block-drivers manpage * part of the system/ Sphinx manual This follows the same pattern we've done for qemu-ga and qemu-nbd. We have to drop a cross-reference from the documentation of the -cdrom option back to the qemu-block-drivers documentation, since they're no longer within the same texinfo document. As noted in a comment, the manpage output is slightly compromised due to limitations in Sphinx. In an ideal world, the HTML output would have the various headings like 'Disk image file formats' as top-level section headings (which then appear in the overall system manual's table-of-contents), and it would not have the section headings which make sense only for the manpage like 'synopsis', 'description', and 'see also'. Unfortunately, the mechanism Sphinx provides for restricting pieces of documentation is limited to the point of being flawed: the 'only::' directive is implemented as a filter that is applied at a very late stage in the document processing pipeline, rather than as an early equivalent of an #ifdef. This means that Sphinx's process of identifying which section heading markup styles are which levels of heading gets confused if the 'only::' directive contains section headings which would affect the heading-level of a later heading. I have opted to prioritise making the HTML format look better, with the compromise being that in the manpage the 'Disk image file formats' &c headings are top-level headings rather than being sub-headings under the traditional 'Description' top-level section title. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> Tested-by: Alex Bennée <alex.bennee@linaro.org> Acked-by: Stefan Hajnoczi <stefanha@redhat.com> Message-id: 20200116141511.16849-4-peter.maydell@linaro.org
This commit is contained in:
Peter Maydell
@@ -342,9 +342,9 @@ ifdef BUILD_DOCS
|
||||
DOCS=qemu-doc.html qemu-doc.txt qemu.1 qemu-img.1
|
||||
DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-nbd.8
|
||||
DOCS+=$(MANUAL_BUILDDIR)/interop/qemu-ga.8
|
||||
DOCS+=$(MANUAL_BUILDDIR)/system/qemu-block-drivers.7
|
||||
DOCS+=docs/interop/qemu-qmp-ref.html docs/interop/qemu-qmp-ref.txt docs/interop/qemu-qmp-ref.7
|
||||
DOCS+=docs/interop/qemu-ga-ref.html docs/interop/qemu-ga-ref.txt docs/interop/qemu-ga-ref.7
|
||||
DOCS+=docs/qemu-block-drivers.7
|
||||
DOCS+=docs/qemu-cpu-models.7
|
||||
DOCS+=$(MANUAL_BUILDDIR)/index.html
|
||||
ifdef CONFIG_VIRTFS
|
||||
@@ -751,7 +751,6 @@ distclean: clean
|
||||
rm -f docs/interop/qemu-qmp-ref.txt docs/interop/qemu-ga-ref.txt
|
||||
rm -f docs/interop/qemu-qmp-ref.pdf docs/interop/qemu-ga-ref.pdf
|
||||
rm -f docs/interop/qemu-qmp-ref.html docs/interop/qemu-ga-ref.html
|
||||
rm -f docs/qemu-block-drivers.7
|
||||
rm -f docs/qemu-cpu-models.7
|
||||
rm -rf .doctrees
|
||||
$(call clean-manual,devel)
|
||||
@@ -828,7 +827,7 @@ ifdef CONFIG_POSIX
|
||||
$(INSTALL_DATA) qemu.1 "$(DESTDIR)$(mandir)/man1"
|
||||
$(INSTALL_DIR) "$(DESTDIR)$(mandir)/man7"
|
||||
$(INSTALL_DATA) docs/interop/qemu-qmp-ref.7 "$(DESTDIR)$(mandir)/man7"
|
||||
$(INSTALL_DATA) docs/qemu-block-drivers.7 "$(DESTDIR)$(mandir)/man7"
|
||||
$(INSTALL_DATA) $(MANUAL_BUILDDIR)/system/qemu-block-drivers.7 "$(DESTDIR)$(mandir)/man7"
|
||||
$(INSTALL_DATA) docs/qemu-cpu-models.7 "$(DESTDIR)$(mandir)/man7"
|
||||
ifeq ($(CONFIG_TOOLS),y)
|
||||
$(INSTALL_DATA) qemu-img.1 "$(DESTDIR)$(mandir)/man1"
|
||||
@@ -1036,6 +1035,9 @@ $(MANUAL_BUILDDIR)/interop/qemu-ga.8: $(call manual-deps,interop)
|
||||
$(MANUAL_BUILDDIR)/interop/qemu-nbd.8: $(call manual-deps,interop)
|
||||
$(call build-manual,interop,man)
|
||||
|
||||
$(MANUAL_BUILDDIR)/system/qemu-block-drivers.7: $(call manual-deps,system)
|
||||
$(call build-manual,system,man)
|
||||
|
||||
$(MANUAL_BUILDDIR)/index.html: $(SRC_PATH)/docs/index.html.in qemu-version.h
|
||||
@mkdir -p "$(MANUAL_BUILDDIR)"
|
||||
$(call quiet-command, sed "s|@@VERSION@@|${VERSION}|g" $< >$@, \
|
||||
@@ -1063,7 +1065,6 @@ qemu.1: qemu-doc.texi qemu-options.texi qemu-monitor.texi qemu-monitor-info.texi
|
||||
qemu.1: qemu-option-trace.texi
|
||||
qemu-img.1: qemu-img.texi qemu-option-trace.texi qemu-img-cmds.texi
|
||||
fsdev/virtfs-proxy-helper.1: fsdev/virtfs-proxy-helper.texi
|
||||
docs/qemu-block-drivers.7: docs/qemu-block-drivers.texi
|
||||
docs/qemu-cpu-models.7: docs/qemu-cpu-models.texi
|
||||
scripts/qemu-trace-stap.1: scripts/qemu-trace-stap.texi
|
||||
|
||||
@@ -1076,7 +1077,7 @@ qemu-doc.html qemu-doc.info qemu-doc.pdf qemu-doc.txt: \
|
||||
qemu-img.texi qemu-options.texi \
|
||||
qemu-tech.texi qemu-option-trace.texi \
|
||||
qemu-deprecated.texi qemu-monitor.texi qemu-img-cmds.texi \
|
||||
qemu-monitor-info.texi docs/qemu-block-drivers.texi \
|
||||
qemu-monitor-info.texi \
|
||||
docs/qemu-cpu-models.texi docs/security.texi
|
||||
|
||||
docs/interop/qemu-ga-ref.dvi docs/interop/qemu-ga-ref.html \
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -13,3 +13,10 @@ exec(compile(open(parent_config, "rb").read(), parent_config, 'exec'))
|
||||
# This slightly misuses the 'description', but is the best way to get
|
||||
# the manual title to appear in the sidebar.
|
||||
html_theme_options['description'] = u'System Emulation User''s Guide'
|
||||
# One entry per manual page. List of tuples
|
||||
# (source start file, name, description, authors, manual section).
|
||||
man_pages = [
|
||||
('qemu-block-drivers', 'qemu-block-drivers',
|
||||
u'QEMU block drivers reference',
|
||||
['Fabrice Bellard and the QEMU Project developers'], 7)
|
||||
]
|
||||
|
||||
@@ -14,3 +14,4 @@ Contents:
|
||||
.. toctree::
|
||||
:maxdepth: 2
|
||||
|
||||
qemu-block-drivers
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -633,16 +633,6 @@ encrypted disk images.
|
||||
* disk_images_snapshot_mode:: Snapshot mode
|
||||
* vm_snapshots:: VM snapshots
|
||||
* qemu_img_invocation:: qemu-img Invocation
|
||||
* disk_images_formats:: Disk image file formats
|
||||
* host_drives:: Using host drives
|
||||
* disk_images_fat_images:: Virtual FAT disk images
|
||||
* disk_images_nbd:: NBD access
|
||||
* disk_images_sheepdog:: Sheepdog disk images
|
||||
* disk_images_iscsi:: iSCSI LUNs
|
||||
* disk_images_gluster:: GlusterFS disk images
|
||||
* disk_images_ssh:: Secure Shell (ssh) disk images
|
||||
* disk_images_nvme:: NVMe userspace driver
|
||||
* disk_image_locking:: Disk image file locking
|
||||
@end menu
|
||||
|
||||
@node disk_images_quickstart
|
||||
@@ -723,8 +713,6 @@ state is not saved or restored properly (in particular USB).
|
||||
|
||||
@include qemu-img.texi
|
||||
|
||||
@include docs/qemu-block-drivers.texi
|
||||
|
||||
@node pcsys_network
|
||||
@section Network emulation
|
||||
|
||||
|
||||
+1
-1
@@ -953,7 +953,7 @@ STEXI
|
||||
@findex -cdrom
|
||||
Use @var{file} as CD-ROM image (you cannot use @option{-hdc} and
|
||||
@option{-cdrom} at the same time). You can use the host CD-ROM by
|
||||
using @file{/dev/cdrom} as filename (@pxref{host_drives}).
|
||||
using @file{/dev/cdrom} as filename.
|
||||
ETEXI
|
||||
|
||||
DEF("blockdev", HAS_ARG, QEMU_OPTION_blockdev,
|
||||
|
||||
Reference in New Issue
Block a user