aboutsummaryrefslogtreecommitdiff
path: root/docs/sphinx
AgeCommit message (Collapse)AuthorFilesLines
2021-04-30qapi/error: Repurpose QAPIError as an abstract base exception classJohn Snow1-1/+2
Rename QAPIError to QAPISourceError, and then create a new QAPIError class that serves as the basis for all of our other custom exceptions, without specifying any class properties. This leaves QAPIError as a package-wide error class that's suitable for any current or future errors. (Right now, we don't have any errors that DON'T also want to specify a Source location, but this MAY change. In these cases, a common abstract ancestor would be desired.) Add docstrings to explain the intended function of each error class. Signed-off-by: John Snow <jsnow@redhat.com> Message-Id: <20210421192233.3542904-2-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
2021-04-13sphinx: qapidoc: Wrap "If" section body in a paragraph nodeJohn Snow1-1/+3
These sections need to be wrapped in a block-level element, such as Paragraph in order for them to be rendered into Texinfo correctly. Before (e.g.): <section ids="qapidoc-713"> <title>If</title> <literal>defined(CONFIG_REPLICATION)</literal> </section> became: .SS If \fBdefined(CONFIG_REPLICATION)\fP.SS \fBBlockdevOptionsReplication\fP (Object) ... After: <section ids="qapidoc-713"> <title>If</title> <paragraph> <literal>defined(CONFIG_REPLICATION)</literal> </paragraph> </section> becomes: .SS If .sp \fBdefined(CONFIG_REPLICATION)\fP .SS \fBBlockdevOptionsReplication\fP (Object) ... Reported-by: Markus Armbruster <armbru@redhat.com> Tested-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: John Snow <jsnow@redhat.com> Reviewed-by: Peter Maydell <peter.maydell@linaro.org> Message-id: 20210406141909.1992225-2-jsnow@redhat.com Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
2021-02-15docs/sphinx/qapidoc.py: Handle change of QAPI's builtin module namePeter Maydell1-1/+1
In commit e2bbc4eaa7f0 we changed the QAPI modules to name the built-in module "./builtin" rather than None, but forgot to update the Sphinx plugin. The effect of this was that when the plugin generated a dependency file it was including a bogus dependency on a non-existent file named "builtin", which meant that ninja would run Sphinx and rebuild all the documentation every time even if nothing had changed. Update the plugin to use the new name of the builtin module. Fixes: e2bbc4eaa7f0 Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Paolo Bonzini <pbonzini@redhat.com> Tested-by: Eric Blake <eblake@redhat.com> Message-id: 20210212161311.28915-1-peter.maydell@linaro.org
2020-12-10Revert "docs: temporarily disable the kernel-doc extension"Paolo Bonzini1-3/+0
This reverts commit fd68a72875cf318f4310726f842139119c5f45d5. We're done with the update of kernel-doc and we can restore kernel-doc's functionality. Signed-off-by: Paolo Bonzini <pbonzini@redhat.com> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2020-12-10scripts: kernel-doc: allow passing desired Sphinx C domain dialectMauro Carvalho Chehab1-0/+5
When kernel-doc is called via kerneldoc.py, there's no need to auto-detect the Sphinx version, as the Sphinx module already knows it. So, add an optional parameter to allow changing the Sphinx dialect. As kernel-doc can also be manually called, keep the auto-detection logic if the parameter was not specified. On such case, emit a warning if sphinx-build can't be found at PATH. I ended using a suggestion from Joe for using a more readable regex, instead of using a complex one with a hidden group like: m/^(\d+)\.(\d+)(?:\.?(\d+)?)/ in order to get the optional <patch> argument. Thanks-to: Joe Perches <joe@perches.com> Suggested-by: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com> Message-Id: <20201117165312.118257-23-pbonzini@redhat.com> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2020-12-10Revert "kernel-doc: Use c:struct for Sphinx 3.0 and later"Paolo Bonzini1-1/+0
This reverts commit 152d1967f650f67b7ece3a5dda77d48069d72647. We will replace the commit with the fix from Linux. Signed-off-by: Paolo Bonzini <pbonzini@redhat.com> Message-Id: <20201117165312.118257-16-pbonzini@redhat.com> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2020-12-10docs: temporarily disable the kernel-doc extensionPaolo Bonzini1-0/+3
Preserve bisectability while we update scripts/kernel-doc from Linux. Without this patch, building with Sphinx 3 would break while we revert our own Sphinx 3 support and replace it with Linux's. Suggested-by: Peter Maydell <peter.maydell@linaro.org> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2020-10-17docs: Fix Sphinx configuration for msys2/mingwYonggang Luo1-1/+1
Python doesn't support running ../scripts/kernel-doc directly. Signed-off-by: Yonggang Luo <luoyonggang@gmail.com> Message-Id: <20201015220626.418-2-luoyonggang@gmail.com> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2020-10-09qapi: Add a 'coroutine' flag for commandsKevin Wolf1-1/+1
This patch adds a new 'coroutine' flag to QMP command definitions that tells the QMP dispatcher that the command handler is safe to be run in a coroutine. The documentation of the new flag pretends that this flag is already used as intended, which it isn't yet after this patch. We'll implement this in another patch in this series. Signed-off-by: Kevin Wolf <kwolf@redhat.com> Message-Id: <20201005155855.256490-9-kwolf@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Stefan Hajnoczi <stefanha@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
2020-09-29docs/sphinx: Add new qapi-doc Sphinx extensionPeter Maydell1-0/+549
Some of our documentation is auto-generated from documentation comments in the JSON schema. For Sphinx, rather than creating a file to include, the most natural way to handle this is to have a small custom Sphinx extension which processes the JSON file and inserts documentation into the rST file being processed. This is the same approach that kerneldoc and hxtool use. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Message-Id: <20200925162316.21205-8-peter.maydell@linaro.org> Reviewed-by: Markus Armbruster <armbru@redhat.com> [Comment and doc string formatting tweaked, unused method dropped, a few line breaks tweaked to follow PEP 8 more closely, MAINTAINERS section QAPI updated] Signed-off-by: Markus Armbruster <armbru@redhat.com>
2020-08-21docs: automatically track manual dependenciesPaolo Bonzini1-0/+51
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2020-04-14kernel-doc: Use c:struct for Sphinx 3.0 and laterPeter Maydell1-0/+1
The kernel-doc Sphinx plugin and associated script currently emit 'c:type' directives for "struct foo" documentation. Sphinx 3.0 warns about this: /home/petmay01/linaro/qemu-from-laptop/qemu/docs/../include/exec/memory.h:3: WARNING: Type must be either just a name or a typedef-like declaration. If just a name: Error in declarator or parameters Invalid C declaration: Expected identifier in nested name, got keyword: struct [error at 6] struct MemoryListener ------^ If typedef-like declaration: Error in declarator or parameters Invalid C declaration: Expected identifier in nested name. [error at 21] struct MemoryListener ---------------------^ because it wants us to use the new-in-3.0 'c:struct' instead. Plumb the Sphinx version through to the kernel-doc script and use it to select 'c:struct' for newer versions than 3.0. Fixes: LP:1872113 Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
2020-03-12docs/sphinx/hxtool.py: Remove STEXI/ETEXI supportPeter Maydell1-24/+4
Now that none of our input .hx files have STEXI/ETEXI blocks, we can remove the code in the Sphinx hxtool extension that supported parsing them. Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Richard Henderson <richard.henderson@linaro.org> Message-id: 20200306171749.10756-5-peter.maydell@linaro.org
2020-03-06doc/scripts/hxtool.py: Strip trailing ':' from DEFHEADING/ARCHHEADINGPeter Maydell1-4/+6
In hxtool files, section headings defined with the DEFHEADING and ARCHHEADING macros have a trailing ':' DEFHEADING(Standard options:) This is for the benefit of the --help output. For consistency with the rest of the rST documentation, strip any trailing ':' when we construct headings with the Sphinx hxtool extension. This makes the table of contents look neater. This only affects generation of documentation from qemu-options.hx, which we will start doing in a later commit. 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-23-peter.maydell@linaro.org
2020-02-03docs/sphinx: Add new hxtool Sphinx extensionPeter Maydell1-0/+210
Some of our documentation includes sections which are created by assembling fragments of texinfo from a .hx source file into a .texi file, which is then included from qemu-doc.texi or qemu-img.texi. For Sphinx, rather than creating a file to include, the most natural way to handle this is to have a small custom Sphinx extension which reads the .hx file and process it. So instead of: * makefile produces foo.texi from foo.hx * qemu-doc.texi says '@include foo.texi' we have: * qemu-doc.rst says 'hxtool-doc:: foo.hx' * the Sphinx extension for hxtool has code that runs to handle that Sphinx directive which reads the .hx file and emits the appropriate documentation contents This is pretty much the same way the kerneldoc extension works right now. It also has the advantage that it should work for third-party services like readthedocs that expect to build the docs directly with sphinx rather than by invoking our makefiles. In this commit we implement the hxtool extension. Note that syntax errors in the rST fragments will be correctly reported to the user with the filename and line number within the hx file. 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-4-peter.maydell@linaro.org
2019-12-17docs: import Linux kernel-doc script and extensionPaolo Bonzini2-0/+200
Import Linux's kernel-doc script as of commit 15e2544ed38a1e, as well as the Sphinx extension to call kernel-doc according to the arguments and parameters given to a reStructuredText directive. The kernel-doc extension accepts a filename, which is relative to the QEMU source tree root. The extension also notifies Sphinx about the document dependency on the file, causing the document to be rebuilt when the file has been changed. Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
2019-07-10sphinx: add qmp_lexerJohn Snow1-0/+43
Sphinx, through Pygments, does not like annotated json examples very much. In some versions of Sphinx (1.7), it will render the non-json portions of code blocks in red, but in newer versions (2.0) it will throw an exception and not highlight the block at all. Though we can suppress this warning, it doesn't bring back highlighting on non-strict json blocks. We can alleviate this by creating a custom lexer for QMP examples that allows us to properly highlight these examples in a robust way, keeping our directionality and elision notations. Signed-off-by: Eduardo Habkost <ehabkost@redhat.com> Signed-off-by: John Snow <jsnow@redhat.com> Reported-by: Aarushi Mehta <mehta.aaru20@gmail.com> Reviewed-by: Peter Maydell <peter.maydell@linaro.org> Message-id: 20190603214653.29369-3-jsnow@redhat.com Signed-off-by: John Snow <jsnow@redhat.com>
generated by cgit v1.1 at 2024-10-21 13:32:00 +0000