riscv/qemu: QEMU main repository: Please see https://www.qemu.org/docs/master/devel/submitting-a-patch.html for how to submit changes to QEMU. Pull Requests are ignored. Please only use release tarballs from the QEMU website. http://www.qemu.org - qemu

QEMU main repository: Please see https://www.qemu.org/docs/master/devel/submitting-a-patch.html for how to submit changes to QEMU. Pull Requests are ignored. Please only use release tarballs from the QEMU website. http://www.qemu.org

emulation kvm qemu virtualization

History

John Snow 3c5f6114d9 qapi: remove "Example" doc section 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>		2 years ago
..
.flake8	qapi: Update flake8 config	3 years ago
.isort.cfg	qapi: enforce import order/styling with isort	6 years ago
__init__.py	qapi-gen: New common driver for code and doc generators	8 years ago
commands.py	qapi: Rename QAPISchemaObjectType.variants to .branches	2 years ago
common.py	qapi: Avoid generating C identifier 'linux'	4 years ago
error.py	qapi/error: Add type hints	5 years ago
events.py	qapi: Rename QAPISchemaObjectType.variants to .branches	2 years ago
expr.py	qapi: Fix to reject 'data': 'mumble' in struct	3 years ago
gen.py	qapi: Rename QAPISchemaObjectType.variants to .branches	2 years ago
introspect.py	qapi: linter fixups	2 years ago
main.py	qapi: Fix error message format regression	3 years ago
mypy.ini	qapi/schema: turn on mypy strictness	2 years ago
parser.py	qapi: remove "Example" doc section	2 years ago
pylintrc	qapi/schema: add pylint suppressions	2 years ago
schema.py	qapi: linter fixups	2 years ago
source.py	qapi: Require member documentation (with loophole)	2 years ago
types.py	qapi: Rename QAPISchemaObjectType.variants to .branches	2 years ago
visit.py	qapi: linter fixups	2 years ago