Since the previous commit, QAPIDoc.Section.name is either
None (untagged section) or the section's tag string ('Returns',
'@name', ...). Rename it to .tag.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240216145841.2099240-9-armbru@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Improve the message for an empty tagged section from
empty doc section 'Note'
to
text required after 'Note:'
and the message for an empty argument or feature description from
empty doc section 'foo'
to
text required after '@foo:'
Improve the error position to refer to the beginning of the empty
section instead of its end.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240216145841.2099240-8-armbru@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Commit 4e99f4b12c (qapi: Drop simple unions) eliminated implicitly
defined union branch types, except for the empty object type
'q_empty'. QAPISchemaGenRSTVisitor._nodes_for_members() still has
code to generate documentation for implicitly defined union branch
types. It does nothing for 'q_empty'. Simplify.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240216145841.2099240-5-armbru@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
QAPISchemaGenRSTVisitor._nodes_for_members() has a special case to
auto-generate documentation for a union tag member of implicit (enum)
type that lacks documentation.
This was useful for simple unions, where the tag member's type was
implicitly. The only implicit enum type left today is 'QType'. Not
worth a special case. Drop. No change to generated documentation.
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-ID: <20240205074709.3613229-6-armbru@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
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>
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>
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>
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>
