We can't just embed labels directly into files like qemu-options.hx which
are included from multiple top-level rST files, because Sphinx sees the
labels as duplicate: https://github.com/sphinx-doc/sphinx/issues/9707
So add an optional argument to the SRST directive which causes a label
of the form '.. _DOCNAME-HXFILE-LABEL:' to be emitted, where 'DOCNAME'
is the name of the top level rST file, 'HXFILE' is the filename of the
.hx file, and 'LABEL' is the text provided within the 'SRST()' directive.
Using the DOCNAME of the top-level rST document means that it is unique
even when the .hx file is included from two different documents, as is
the case for qemu-options.hx
Now where the Xen PV documentation refers to the documentation for the
-initrd command line option, it can emit a link directly to it as
'<system/invocation-qemu-options-initrd>'.
Signed-off-by: David Woodhouse <dwmw@amazon.co.uk>
Reviewed-by: Paul Durrant <paul@xen.org>
Reviewed-by: Peter Maydell <peter.maydell@linaro.org>
Message-id: 20240130190348.682912-1-dwmw2@infradead.org
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Pylint advises:
docs/sphinx/qapidoc.py:518:12: W0707: Consider explicitly re-raising using 'raise ExtensionError(str(err)) from err' (raise-missing-from)
>From its manual:
Python's exception chaining shows the traceback of the current
exception, but also of the original exception. When you raise a
new exception after another exception was caught it's likely that
the second exception is a friendly re-wrapping of the first
exception. In such cases `raise from` provides a better link
between the two tracebacks in the final error.
Makes sense, so do it.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20231025092159.1782638-2-armbru@redhat.com>
Reviewed-by: John Snow <jsnow@redhat.com>
Save a bit of build time by passing the number of jobs option to
sphinx.
We cannot use the -j option from make because meson does not support
setting build time parameters for custom targets. Use nproc instead or
the equivalent sphinx option "-j auto", if that is available (version
>=1.7.0).
Also make sure our plugins support parallelism and report it properly
to sphinx. Particularly, implement the merge_domaindata method in
DBusDomain that is used to merge in data from other subprocesses.
Tested-by: Daniel P. Berrangé <berrange@redhat.com>
Signed-off-by: Fabiano Rosas <farosas@suse.de>
Message-Id: <20230503203947.3417-2-farosas@suse.de>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
QAPI doc comments are for QMP users: they go into the "QEMU QMP
Reference Manual" and the "QEMU Storage Daemon QMP Reference Manual".
The doc comment TODO sections are for somebody else, namely for the
people who can do: developers. Do not emit them into the user
manuals.
This elides the following TODOs:
* SchemaInfoCommand
# TODO: @success-response (currently irrelevant, because it's QGA, not QMP)
This is a note to developers adding introspection to the guest
agent. It makes no sense to users.
* @query-hotpluggable-cpus
# TODO: Better documentation; currently there is none.
This is a reminder for developers. It doesn't help users.
* @device_add
# TODO: This command effectively bypasses QAPI completely due to its
# "additional arguments" business. It shouldn't have been added to
# the schema in this form. It should be qapified properly, or
# replaced by a properly qapified command.
Likewise.
Eliding them is an improvement.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20230428105429.1687850-7-armbru@redhat.com>
Reviewed-by: Ani Sinha <anisinha@redhat.com>
Reviewed-by: Juan Quintela <quintela@redhat.com>
Currently, the kerneldoc Sphinx plugin doesn't honour the
--enable-werror configure option, so its warnings are never fatal.
This is because although we do pass sphinx-build the -W switch, the
warnings from kerneldoc are produced by the scripts/kernel-doc script
directly and don't go through Sphinx's "emit a warning" function.
When --enable-werror is in effect, pass sphinx-build an extra
argument -Dkerneldoc_werror=1. The kerneldoc plugin can then use
this to determine whether it should be passing the kernel-doc script
-Werror.
We do this because there is no documented mechanism for
a Sphinx plugin to determine whether sphinx-build was
passed -W or not; if one is provided then we can switch to
that at a later date:
https://github.com/sphinx-doc/sphinx/issues/11239
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Reviewed-by: Thomas Huth <thuth@redhat.com>
Message-Id: <20230314114431.1096972-1-peter.maydell@linaro.org>
Signed-off-by: Laurent Vivier <laurent@vivier.eu>
SphinxDirective was added with sphinx 1.8 (2018-09-13).
Reported-by: Thomas Huth <thuth@redhat.com>
Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Tested-by: Thomas Huth <thuth@redhat.com>
Message-Id: <20220104074649.1712440-1-marcandre.lureau@redhat.com>
Signed-off-by: Thomas Huth <thuth@redhat.com>
Add a new dbus-doc directive to import D-Bus interfaces documentation
from the introspection XML. The comments annotations follow the
gtkdoc/kerneldoc style, and should be formatted with reST.
Note: I realize after the fact that I was implementing those modules
with sphinx 4, and that we have much lower requirements. Instead of
lowering the features and code (removing type annotations etc), let's
have a warning in the documentation when the D-Bus modules can't be
used, and point to the source XML file in that case.
Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Acked-by: Gerd Hoffmann <kraxel@redhat.com>
Instead of building the condition documentation from a list of string,
use the result generated from QAPISchemaIfCond.docgen().
This changes the generated documentation from:
- COND1, COND2... (where COND1, COND2 are Literal nodes, and ',' is Text)
to:
- COND1 and COND2 (the whole string as a Literal node)
This will allow us to generate more complex conditions in the following
patches, such as "(COND1 and COND2) or COND3".
Adding back the differentiated formatting is left to the wish list.
Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Message-Id: <20210804083105.97531-6-marcandre.lureau@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[TODO comment added]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Mechanical change, except for a new assertion in
QAPISchemaEntity.ifcond().
Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Message-Id: <20210804083105.97531-3-marcandre.lureau@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Rebased with obvious conflicts, commit message adjusted]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
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>
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>
In commit e2bbc4eaa7 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: e2bbc4eaa7
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
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>
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>
This reverts commit 152d1967f6.
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>
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>
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>
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>
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>
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
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
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
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>
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>
