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

Makefile

@@ -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 \

docs/system/conf.py

@@ -13,3 +13,10 @@
 # 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)
+]

docs/system/index.rst

@@ -14,3 +14,4 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
+   qemu-block-drivers

qemu-doc.texi

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

qemu-options.hx

@@ -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,