aboutsummaryrefslogtreecommitdiff
path: root/docs/system/conf.py
AgeCommit message (Collapse)Author
2021-01-19docs: Build and install all the docs in a single manualPeter Maydell
When we first converted our documentation to Sphinx, we split it into multiple manuals (system, interop, tools, etc), which are all built separately. The primary driver for this was wanting to be able to avoid shipping the 'devel' manual to end-users. However, this is working against the grain of the way Sphinx wants to be used and causes some annoyances: * Cross-references between documents become much harder or possibly impossible * There is no single index to the whole documentation * Within one manual there's no links or table-of-contents info that lets you easily navigate to the others * The devel manual doesn't get published on the QEMU website (it would be nice to able to refer to it there) Merely hiding our developer documentation from end users seems like it's not enough benefit for these costs. Combine all the documentation into a single manual (the same way that the readthedocs site builds it) and install the whole thing. The previous manual divisions remain as the new top level sections in the manual. * The per-manual conf.py files are no longer needed * The man_pages[] specifications previously in each per-manual conf.py move to the top level conf.py * docs/meson.build logic is simplified as we now only need to run Sphinx once for the HTML and then once for the manpages5B * The old index.html.in that produced the top-level page with links to each manual is no longer needed Unfortunately this means that we now have to build the HTML documentation into docs/manual in the build tree rather than directly into docs/; otherwise it is too awkward to ensure we install only the built manual and not also the dependency info, stamp file, etc. The manual still ends up in the same place in the final installed directory, but anybody who was consulting documentation from within the build tree will have to adjust where they're looking. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Paolo Bonzini <pbonzini@redhat.com> Message-id: 20210115154449.4801-1-peter.maydell@linaro.org
2020-03-06docs: Generate qemu.1 manpage with SphinxPeter Maydell
Generate the qemu.1 manpage using Sphinx; we do this with a new top-level rst source file which is just the skeleton of the manpage and which includes .rst.inc fragments where it needs to incorporate sections from the larger HTML manuals. 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: 20200228153619.9906-30-peter.maydell@linaro.org
2020-03-06docs/system: Convert qemu-cpu-models.texi to rSTKashyap Chamarthy
This doc was originally written by Daniel P. Berrangé <berrange@redhat.com>, introduced via commit[1]: 2544e9e4aa (docs: add guidance on configuring CPU models for x86, 2018-06-27). In this patch: - 1-1 conversion of Texinfo to rST, besides a couple of minor tweaks that are too trivial to mention. (Thanks to Stephen Finucane on IRC for the suggestion to use rST "definition lists" instead of bullets in some places.) Further modifications will be done via a separate patch. - rST and related infra changes: manual page generation, Makefile fixes, clean up references to qemu-cpu-models.texi, update year in the copyright notice, etc. [1] https://git.qemu.org/?p=qemu.git;a=commit;h=2544e9e4aa As part of the conversion, we use a more generic 'author' attribution for the manpage than we previously had, as agreed with the original author Dan Berrange. Signed-off-by: Kashyap Chamarthy <kchamart@redhat.com> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> Tested-by: Alex Bennée <alex.bennee@linaro.org> Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Message-id: 20200228153619.9906-16-peter.maydell@linaro.org Message-id: 20200226113034.6741-15-pbonzini@redhat.com [Move macros to defs.rst.inc, split in x86 and MIPS parts, make qemu-cpu-models.rst a standalone document. - Paolo] Signed-off-by: Paolo Bonzini <pbonzini@redhat.com> [PMM: Move defs.rst.inc setup to its own commit; fix minor issues with MAINTAINERS file updates; drop copyright date change; keep capitalization of "QEMU Project developers" consistent with other uses; minor Makefile fixups] Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
2020-01-23qemu-block-drivers: Convert to rSTPeter Maydell
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
2020-01-23docs: Create stub system manualPeter Maydell
We want a user-facing manual which contains system emulation documentation. Create an empty one which we can populate. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Alex Bennée <alex.bennee@linaro.org> Acked-by: Stefan Hajnoczi <stefanha@redhat.com> Message-id: 20200116141511.16849-3-peter.maydell@linaro.org