mirrors/qemu
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
605ffebb2e
qemu/docs/interop/conf.py

29 lines
1.1 KiB
Python
Raw Normal View History

docs: Provide separate conf.py for each manual we want By default Sphinx wants to build a single manual at once. For QEMU, this doesn't suit us, because we want to have separate manuals for "Developer's Guide", "User Manual", and so on, and we don't want to ship the Developer's Guide to end-users. However, we don't want to completely duplicate conf.py for each manual, and we'd like to continue to support "build all docs in one run" for third-party sites like readthedocs.org. Make the top-level conf.py support two usage forms: (1) as a common config file which is included by the conf.py for each of QEMU's manuals: in this case sphinx-build is run multiple times, once per subdirectory. (2) as a top level conf file which will result in building all the manuals into a single document: in this case sphinx-build is run once, on the top-level docs directory. Provide per-manual conf.py files and top level pages for our first two manuals: * QEMU Developer's Guide (docs/devel) * QEMU System Emulation Management and Interoperability Guide (docs/interop) Reviewed-by: Alex Bennée <alex.bennee@linaro.org> Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Acked-by: Aleksandar Markovic <amarkovic@wavecomp.com> Message-id: 20190305172139.32662-9-peter.maydell@linaro.org Message-id: 20190228145624.24885-9-peter.maydell@linaro.org
2019-03-07 17:26:46 +03:00
# -*- coding: utf-8 -*-
#
# QEMU documentation build configuration file for the 'interop' 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 Management and Interoperability Guide'
qemu-ga: Convert invocation documentation to rST The qemu-ga documentation is currently in qemu-ga.texi in Texinfo format, which we present to the user as: * a qemu-ga 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-ga manpage * part of the interop/ Sphinx manual Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Michael Roth <mdroth@linux.vnet.ibm.com> Tested-by: Michael Roth <mdroth@linux.vnet.ibm.com> Message-id: 20190905131040.8350-1-peter.maydell@linaro.org
2019-09-05 16:10:40 +03:00
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('qemu-ga', 'qemu-ga', u'QEMU Guest Agent',
qemu-nbd: Convert invocation documentation to rST The qemu-nbd documentation is currently in qemu-nbd.texi in Texinfo format, which we present to the user as: * a qemu-nbd 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-nbd manpage * part of the interop/ Sphinx manual This follows the same pattern as commit 27a296fce982 did for the qemu-ga manpage. All the content of the old manpage is retained, except that I have dropped the "This is free software; see the source for copying conditions. There is NO warranty..." text that was in the old AUTHOR section; Sphinx's manpage builder doesn't expect that much text in the AUTHOR section, and since none of our other manpages have it it seems easiest to delete it rather than try to figure out where else in the manpage to put it. The only other textual change is that I have had to give the --nocache option its own description ("Equivalent to --cache=none") because Sphinx doesn't have an equivalent of using item/itemx to share a description between two options. Some minor aspects of the formatting have changed, to suit what is easiest for Sphinx to output. (The most notable is that Sphinx option section option syntax doesn't support '--option foo=bar' with bar underlined rather than bold, so we have to switch to '--option foo=BAR' instead.) The contents of qemu-option-trace.texi are now duplicated in docs/interop/qemu-option-trace.rst.inc, until such time as we complete the conversion of the other files which use it; since it has had only 3 changes in 3 years, this shouldn't be too awkward a burden. (We use .rst.inc because if this file fragment has a .rst extension then Sphinx complains about not seeing it in a toctree.) Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> Reviewed-by: Eric Blake <eblake@redhat.com> Tested-by: Alex Bennée <alex.bennee@linaro.org> Acked-by: Stefan Hajnoczi <stefanha@redhat.com> Message-id: 20200116141511.16849-2-peter.maydell@linaro.org
2020-01-23 18:22:39 +03:00
['Michael Roth <mdroth@linux.vnet.ibm.com>'], 8),
qemu-img: Convert invocation documentation to rST The qemu-img documentation is currently in qemu-nbd.texi in Texinfo format, which we present to the user as: * a qemu-img 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-img manpage * part of the interop/ Sphinx manual The qemu-img rST document uses the new hxtool extension to handle pulling rST fragments out of qemu-img-cmds.hx. The documentation of the various options and commands is rather muddled, with some options being described inside the relevant command description and some in a more general section near the start of the manual. All the command synopses are replicated in the .hx file and then again in the manual. A lot of text is also duplicated in the qemu-img.c code for the help text. I have not attempted to deal with any of this, but have simply transposed the existing structure into rST. As usual, there are some minor formatting changes but no textual changes, except that as with one or two other conversions I have dropped the 'see also' section since it's not very informative and looks odd in the HTML. 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> Message-id: 20200124162606.8787-6-peter.maydell@linaro.org
2020-01-24 19:26:03 +03:00
('qemu-img', 'qemu-img', u'QEMU disk image utility',
['Fabrice Bellard'], 1),
qemu-nbd: Convert invocation documentation to rST The qemu-nbd documentation is currently in qemu-nbd.texi in Texinfo format, which we present to the user as: * a qemu-nbd 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-nbd manpage * part of the interop/ Sphinx manual This follows the same pattern as commit 27a296fce982 did for the qemu-ga manpage. All the content of the old manpage is retained, except that I have dropped the "This is free software; see the source for copying conditions. There is NO warranty..." text that was in the old AUTHOR section; Sphinx's manpage builder doesn't expect that much text in the AUTHOR section, and since none of our other manpages have it it seems easiest to delete it rather than try to figure out where else in the manpage to put it. The only other textual change is that I have had to give the --nocache option its own description ("Equivalent to --cache=none") because Sphinx doesn't have an equivalent of using item/itemx to share a description between two options. Some minor aspects of the formatting have changed, to suit what is easiest for Sphinx to output. (The most notable is that Sphinx option section option syntax doesn't support '--option foo=bar' with bar underlined rather than bold, so we have to switch to '--option foo=BAR' instead.) The contents of qemu-option-trace.texi are now duplicated in docs/interop/qemu-option-trace.rst.inc, until such time as we complete the conversion of the other files which use it; since it has had only 3 changes in 3 years, this shouldn't be too awkward a burden. (We use .rst.inc because if this file fragment has a .rst extension then Sphinx complains about not seeing it in a toctree.) Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> Reviewed-by: Eric Blake <eblake@redhat.com> Tested-by: Alex Bennée <alex.bennee@linaro.org> Acked-by: Stefan Hajnoczi <stefanha@redhat.com> Message-id: 20200116141511.16849-2-peter.maydell@linaro.org
2020-01-23 18:22:39 +03:00
('qemu-nbd', 'qemu-nbd', u'QEMU Disk Network Block Device Server',
scripts/qemu-trace-stap: Convert documentation to rST The qemu-trace-stap documentation is currently in scripts/qemu-trace-stap.texi in Texinfo format, which we present to the user as: * a qemu-trace-stap manpage * but not (unusually for QEMU) part of the HTML docs Convert the documentation to rST format that lives in the docs/ subdirectory, and present it to the user as: * a qemu-trace-stap manpage * part of the interop/ Sphinx manual There are minor formatting changes to suit Sphinx, but no content changes. 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> Message-id: 20200124162606.8787-8-peter.maydell@linaro.org
2020-01-24 19:26:05 +03:00
['Anthony Liguori <anthony@codemonkey.ws>'], 8),
('qemu-trace-stap', 'qemu-trace-stap', u'QEMU SystemTap trace tool',
[], 1)
qemu-ga: Convert invocation documentation to rST The qemu-ga documentation is currently in qemu-ga.texi in Texinfo format, which we present to the user as: * a qemu-ga 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-ga manpage * part of the interop/ Sphinx manual Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Michael Roth <mdroth@linux.vnet.ibm.com> Tested-by: Michael Roth <mdroth@linux.vnet.ibm.com> Message-id: 20190905131040.8350-1-peter.maydell@linaro.org
2019-09-05 16:10:40 +03:00
]
Reference in New Issue Copy Permalink