3c5f6114d9
Fully eliminate the "Example" sections in QAPI doc blocks now that they
have all been converted to arbitrary rST syntax using the
".. qmp-example::" directive. Update tests to match.
Migrating to the new syntax
---------------------------
The old "Example:" or "Examples:" section syntax is now caught as an
error, but "Example::" is stil permitted as explicit rST syntax for an
un-lexed, generic preformatted text block.
('Example' is not special in this case, any sentence that ends with "::"
will start an indented code block in rST.)
Arbitrary rST for Examples is now possible, but it's strongly
recommended that documentation authors use the ".. qmp-example::"
directive for consistent visual formatting in rendered HTML docs. The
":title:" directive option may be used to add extra information into the
title bar for the example. The ":annotated:" option can be used to write
arbitrary rST instead, with nested "::" blocks applying QMP formatting
where desired.
Other choices available are ".. code-block:: QMP" which will not create
an "Example:" box, or the short-form "::" code-block syntax which will
not apply QMP highlighting when used outside of the qmp-example
directive.
Why?
----
This patch has several benefits:
1. Example sections can now be written more arbitrarily, mixing
explanatory paragraphs and code blocks however desired.
2. Example sections can now use fully arbitrary rST.
3. All code blocks are now lexed and validated as QMP; increasing
usability of the docs and ensuring validity of example snippets.
(To some extent - This patch only gaurantees it lexes correctly, not
that it's valid under the JSON or QMP grammars. It will catch most
small mistakes, however.)
4. Each qmp-example can be titled or annotated independently without
bypassing the QMP lexer/validator.
(i.e. code blocks are now for *code* only, so we don't have to
sacrifice exposition for having lexically valid examples.)
NOTE: As with the "Notes" conversion (d461c27973), this patch (and the
three preceding) may change the rendering order for Examples in
the current generator. The forthcoming qapidoc rewrite will fix
this by always generating documentation in source order.
Signed-off-by: John Snow <jsnow@redhat.com>
Message-ID: <20240717021312.606116-10-jsnow@redhat.com>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
226 lines
3.6 KiB
Python
226 lines
3.6 KiB
Python
# -*- Mode: Python -*-
|
|
# vim: filetype=python
|
|
#
|
|
# Positive QAPI doc comment tests
|
|
|
|
{ 'pragma': {
|
|
'doc-required': true,
|
|
'documentation-exceptions': [ 'Enum', 'Variant1', 'Alternate', 'cmd' ] } }
|
|
|
|
##
|
|
# = Section
|
|
##
|
|
|
|
##
|
|
# == Subsection
|
|
#
|
|
# *with emphasis*
|
|
# @var {in braces}
|
|
#
|
|
# * List item one
|
|
# * Two, multiple
|
|
# lines
|
|
#
|
|
# * Three
|
|
# Still in list
|
|
#
|
|
# Not in list
|
|
#
|
|
# - Second list
|
|
# Note: still in list
|
|
#
|
|
# Note: not in list
|
|
#
|
|
# 1. Third list
|
|
# is numbered
|
|
#
|
|
# 2. another item
|
|
#
|
|
# Returns: the King
|
|
# Since: the first age
|
|
# Notes:
|
|
#
|
|
# 1. Lorem ipsum dolor sit amet
|
|
#
|
|
# 2. Ut enim ad minim veniam
|
|
#
|
|
# Duis aute irure dolor
|
|
#
|
|
# Example:
|
|
#
|
|
# -> in
|
|
# <- out
|
|
# Examples:
|
|
# - *verbatim*
|
|
# - {braces}
|
|
##
|
|
|
|
# Not a doc comment
|
|
|
|
##
|
|
# @Enum:
|
|
#
|
|
# @one: The _one_ {and only}, description on the same line
|
|
#
|
|
# Features:
|
|
# @enum-feat: Also _one_ {and only}
|
|
# @enum-member-feat: a member feature
|
|
#
|
|
# @two is undocumented
|
|
##
|
|
{ 'enum': 'Enum',
|
|
'data': [ { 'name': 'one', 'if': 'IFONE',
|
|
'features': [ 'enum-member-feat' ] },
|
|
'two' ],
|
|
'features': [ 'enum-feat' ],
|
|
'if': 'IFCOND' }
|
|
|
|
##
|
|
# @Base:
|
|
#
|
|
# @base1:
|
|
# description starts on a new line,
|
|
# minimally indented
|
|
##
|
|
{ 'struct': 'Base', 'data': { 'base1': 'Enum' },
|
|
'if': { 'all': ['IFALL1', 'IFALL2'] } }
|
|
|
|
##
|
|
# @Variant1:
|
|
#
|
|
# A paragraph
|
|
#
|
|
# Another paragraph
|
|
#
|
|
# @var1 is undocumented
|
|
#
|
|
# Features:
|
|
# @variant1-feat: a feature
|
|
# @member-feat: a member feature
|
|
##
|
|
{ 'struct': 'Variant1',
|
|
'features': [ 'variant1-feat' ],
|
|
'data': { 'var1': { 'type': 'str',
|
|
'features': [ 'member-feat' ],
|
|
'if': 'IFSTR' } } }
|
|
|
|
##
|
|
# @Variant2:
|
|
#
|
|
##
|
|
{ 'struct': 'Variant2', 'data': {} }
|
|
|
|
##
|
|
# @Object:
|
|
#
|
|
# Features:
|
|
# @union-feat1: a feature
|
|
##
|
|
{ 'union': 'Object',
|
|
'features': [ 'union-feat1' ],
|
|
'base': 'Base',
|
|
'discriminator': 'base1',
|
|
'data': { 'one': 'Variant1',
|
|
'two': { 'type': 'Variant2',
|
|
'if': { 'any': ['IFONE', 'IFTWO'] } } } }
|
|
|
|
##
|
|
# @Alternate:
|
|
#
|
|
# @i: description starts on the same line
|
|
# remainder indented the same
|
|
# @b is undocumented
|
|
#
|
|
# Features:
|
|
# @alt-feat: a feature
|
|
##
|
|
{ 'alternate': 'Alternate',
|
|
'features': [ 'alt-feat' ],
|
|
'data': { 'i': 'int', 'b': 'bool' },
|
|
'if': { 'not': { 'any': [ 'IFONE', 'IFTWO' ] } } }
|
|
|
|
##
|
|
# == Another subsection
|
|
##
|
|
|
|
##
|
|
# @cmd:
|
|
#
|
|
# @arg1:
|
|
# description starts on a new line,
|
|
# indented
|
|
#
|
|
# @arg2: description starts on the same line
|
|
# remainder indented differently
|
|
#
|
|
# Features:
|
|
# @cmd-feat1: a feature
|
|
# @cmd-feat2: another feature
|
|
#
|
|
# .. note:: @arg3 is undocumented
|
|
#
|
|
# Returns: @Object
|
|
#
|
|
# Errors: some
|
|
#
|
|
# TODO: frobnicate
|
|
#
|
|
# .. admonition:: Notes
|
|
#
|
|
# - Lorem ipsum dolor sit amet
|
|
# - Ut enim ad minim veniam
|
|
#
|
|
# Duis aute irure dolor
|
|
#
|
|
# .. qmp-example::
|
|
# :title: Ideal fast-food burger situation
|
|
#
|
|
# -> "in"
|
|
# <- "out"
|
|
#
|
|
# Examples::
|
|
#
|
|
# - Not a QMP code block
|
|
# - Merely a preformatted code block literal
|
|
# It isn't even an rST list.
|
|
# - *verbatim*
|
|
# - {braces}
|
|
#
|
|
# Note::
|
|
# Ceci n'est pas une note
|
|
#
|
|
# Since: 2.10
|
|
##
|
|
{ 'command': 'cmd',
|
|
'data': { 'arg1': 'int', '*arg2': 'str', 'arg3': 'bool' },
|
|
'returns': 'Object',
|
|
'features': [ 'cmd-feat1', 'cmd-feat2' ] }
|
|
|
|
##
|
|
# @cmd-boxed:
|
|
# If you're bored enough to read this, go see a video of boxed cats
|
|
#
|
|
# Features:
|
|
# @cmd-feat1: a feature
|
|
# @cmd-feat2: another feature
|
|
#
|
|
# .. qmp-example::
|
|
#
|
|
# -> "this example"
|
|
#
|
|
# <- "has no title"
|
|
##
|
|
{ 'command': 'cmd-boxed', 'boxed': true,
|
|
'data': 'Object',
|
|
'features': [ 'cmd-feat1', 'cmd-feat2' ] }
|
|
|
|
##
|
|
# @EVT_BOXED:
|
|
#
|
|
# Features:
|
|
# @feat3: a feature
|
|
##
|
|
{ 'event': 'EVT_BOXED', 'boxed': true,
|
|
'features': [ 'feat3' ],
|
|
'data': 'Object' }
|