acab923dce
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
23 lines
819 B
Python
23 lines
819 B
Python
# -*- coding: utf-8 -*-
|
|
#
|
|
# QEMU documentation build configuration file for the 'system' manual.
|
|
#
|
|
# This includes the top level conf file and then makes any necessary tweaks.
|
|
import sys
|
|
import os
|
|
|
|
qemu_docdir = os.path.abspath("..")
|
|
parent_config = os.path.join(qemu_docdir, "conf.py")
|
|
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)
|
|
]
|