Revision tags: v9.1.0 |
|
#
01bed0ff |
| 29-Jul-2024 |
Markus Armbruster <armbru@redhat.com> |
qapi: Refill doc comments to conform to conventions
Sweep the entire documentation again. Last done in commit 209e64d9edf (qapi: Refill doc comments to conform to current conventions).
To check th
qapi: Refill doc comments to conform to conventions
Sweep the entire documentation again. Last done in commit 209e64d9edf (qapi: Refill doc comments to conform to current conventions).
To check the generated documentation does not change, I compared the generated HTML before and after this commit with "wdiff -3". Finds no differences. Comparing with diff is not useful, as the reflown paragraphs are visible there.
Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240729065220.860163-1-armbru@redhat.com> [Straightforward conflict with commit 442110bc6f3 resolved]
show more ...
|
#
14b48aaa |
| 16-Jul-2024 |
John Snow <jsnow@redhat.com> |
qapi: convert "Example" sections without titles
Use the no-option form of ".. qmp-example::" to convert any Examples that do not have any form of caption or explanation whatsoever. Note that in a fe
qapi: convert "Example" sections without titles
Use the no-option form of ".. qmp-example::" to convert any Examples that do not have any form of caption or explanation whatsoever. Note that in a few cases, example sections are split into two or more separate example blocks. This is only done stylistically to create a delineation between two or more logically independent examples.
See commit-3: "docs/qapidoc: create qmp-example directive", for a detailed explanation of this custom directive syntax.
See commit+3: "qapi: remove "Example" doc section" for a detailed explanation of why.
Note: an empty "TODO" line was added to announce-self to keep the example from floating up into the body; this will be addressed more rigorously in the new qapidoc generator.
Signed-off-by: John Snow <jsnow@redhat.com> Message-ID: <20240717021312.606116-7-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> [Markup fixed in one place] Signed-off-by: Markus Armbruster <armbru@redhat.com>
show more ...
|
#
fbcb6e0c |
| 11-Jul-2024 |
Markus Armbruster <armbru@redhat.com> |
qapi/pci: Clean up documentation around PciDeviceClass
PciDeviceInfo's doc comment has a note on PciDeviceClass member @desc. Since the note applies always, not just within PciDeviceInfo, merge it i
qapi/pci: Clean up documentation around PciDeviceClass
PciDeviceInfo's doc comment has a note on PciDeviceClass member @desc. Since the note applies always, not just within PciDeviceInfo, merge it into PciDeviceClass's description of member @desc.
Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240711112228.2140606-2-armbru@redhat.com> Reviewed-by: Michael S. Tsirkin <mst@redhat.com> Reviewed-by: John Snow <jsnow@redhat.com>
show more ...
|
#
d461c279 |
| 26-Jun-2024 |
John Snow <jsnow@redhat.com> |
qapi: convert "Note" sections to plain rST
We do not need a dedicated section for notes. By eliminating a specially parsed section, these notes can be treated as normal rST paragraphs in the new QMP
qapi: convert "Note" sections to plain rST
We do not need a dedicated section for notes. By eliminating a specially parsed section, these notes can be treated as normal rST paragraphs in the new QMP reference manual, and can be placed and styled much more flexibly.
Convert all existing "Note" and "Notes" sections to pure rST. As part of the conversion, capitalize the first letter of each sentence and add trailing punctuation where appropriate to ensure notes look sensible and consistent in rendered HTML documentation. Markup is also re-aligned to the de-facto standard of 3 spaces for directives.
Update docs/devel/qapi-code-gen.rst to reflect the new paradigm, and update the QAPI parser to prohibit "Note" sections while suggesting a new syntax. The exact formatting to use is a matter of taste, but a good candidate is simply:
.. note:: lorem ipsum ... ... dolor sit amet ... ... consectetur adipiscing elit ...
... but there are other choices, too. The Sphinx readthedocs theme offers theming for the following forms (capitalization unimportant); all are adorned with a (!) symbol () in the title bar for rendered HTML docs.
See https://sphinx-rtd-theme.readthedocs.io/en/stable/demo/demo.html#admonitions for examples of each directive/admonition in use.
These are rendered in orange:
.. Attention:: ... .. Caution:: ... .. WARNING:: ...
These are rendered in red:
.. DANGER:: ... .. Error:: ...
These are rendered in green:
.. Hint:: ... .. Important:: ... .. Tip:: ...
These are rendered in blue:
.. Note:: ... .. admonition:: custom title
admonition body text
This patch uses ".. note::" almost everywhere, with just two "caution" directives. Several instances of "Notes:" have been converted to merely ".. note::", or multiple ".. note::" where appropriate. ".. admonition:: notes" is used in a few places where we had an ordered list of multiple notes that would not make sense as standalone/separate admonitions. Two "Note:" following "Example:" have been turned into ordinary paragraphs within the example.
NOTE: Because qapidoc.py does not attempt to preserve source ordering of sections, the conversion of Notes from a "tagged section" to an "untagged section" means that rendering order for some notes *may change* as a result of this patch. The forthcoming qapidoc.py rewrite strictly preserves source ordering in the rendered documentation, so this issue will be rectified in the new generator.
Signed-off-by: John Snow <jsnow@redhat.com> Acked-by: Stefan Hajnoczi <stefanha@redhat.com> [for block*.json] Message-ID: <20240626222128.406106-11-jsnow@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> [Commit message clarified slightly, period added to one more note] Signed-off-by: Markus Armbruster <armbru@redhat.com>
show more ...
|
#
d23055b8 |
| 16-Feb-2024 |
Markus Armbruster <armbru@redhat.com> |
qapi: Require descriptions and tagged sections to be indented
By convention, we indent the second and subsequent lines of descriptions and tagged sections, except for examples.
Turn this into a har
qapi: Require descriptions and tagged sections to be indented
By convention, we indent the second and subsequent lines of descriptions and tagged sections, except for examples.
Turn this into a hard rule, and apply it to examples, too.
Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-ID: <20240216145841.2099240-11-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> [Straightforward conflicts in qapi/migration.json resolved]
show more ...
|
#
a937b6aa |
| 28-Apr-2023 |
Markus Armbruster <armbru@redhat.com> |
qapi: Reformat doc comments to conform to current conventions
Change
# @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed # do eiusmod tempor incididunt ut labore et
qapi: Reformat doc comments to conform to current conventions
Change
# @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed # do eiusmod tempor incididunt ut labore et dolore magna aliqua.
to
# @name: Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed # do eiusmod tempor incididunt ut labore et dolore magna aliqua.
See recent commit "qapi: Relax doc string @name: description indentation rules" for rationale.
Reflow paragraphs to 70 columns width, and consistently use two spaces to separate sentences.
To check the generated documentation does not change, I compared the generated HTML before and after this commit with "wdiff -3". Finds no differences. Comparing with diff is not useful, as the reflown paragraphs are visible there.
Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20230428105429.1687850-18-armbru@redhat.com> Reviewed-by: Juan Quintela <quintela@redhat.com> Acked-by: Lukas Straub <lukasstraub2@web.de> [Straightforward conflicts in qapi/audio.json qapi/misc-target.json qapi/run-state.json resolved]
show more ...
|
Revision tags: v8.0.0, v7.2.0, v7.0.0, v6.2.0, v6.1.0 |
|
#
b785d25e |
| 11-Dec-2020 |
Peter Maydell <peter.maydell@linaro.org> |
Merge remote-tracking branch 'remotes/bonzini-gitlab/tags/for-upstream' into staging * Fix for NULL segments (Bin Meng) * Support for 32768 CPUs on x86 without IOMMU (David) * PDEP/P
Merge remote-tracking branch 'remotes/bonzini-gitlab/tags/for-upstream' into staging * Fix for NULL segments (Bin Meng) * Support for 32768 CPUs on x86 without IOMMU (David) * PDEP/PEXT fix and testcase (myself) * Remove bios_name and ram_size globals (myself) * qemu_init rationalization (myself) * Update kernel-doc (myself + upstream patches) * Propagate MemTxResult across DMA and PCI functions (Philippe) * Remove master/slave when applicable (Philippe) * WHPX support for in-kernel irqchip (Sunil) # gpg: Signature made Thu 10 Dec 2020 17:21:50 GMT # gpg: using RSA key F13338574B662389866C7682BFFBD25F78C7AE83 # gpg: issuer "pbonzini@redhat.com" # gpg: Good signature from "Paolo Bonzini <bonzini@gnu.org>" [full] # gpg: aka "Paolo Bonzini <pbonzini@redhat.com>" [full] # Primary key fingerprint: 46F5 9FBD 57D6 12E7 BFD4 E2F7 7E15 100C CD36 69B1 # Subkey fingerprint: F133 3857 4B66 2389 866C 7682 BFFB D25F 78C7 AE83 * remotes/bonzini-gitlab/tags/for-upstream: (113 commits) scripts: kernel-doc: remove unnecessary change wrt Linux Revert "docs: temporarily disable the kernel-doc extension" scripts: kernel-doc: use :c:union when needed scripts: kernel-doc: split typedef complex regex scripts: kernel-doc: fix typedef parsing Revert "kernel-doc: Handle function typedefs that return pointers" Revert "kernel-doc: Handle function typedefs without asterisks" scripts: kernel-doc: try to use c:function if possible scripts: kernel-doc: fix line number handling scripts: kernel-doc: allow passing desired Sphinx C domain dialect scripts: kernel-doc: don't mangle with parameter list scripts: kernel-doc: fix typedef identification scripts: kernel-doc: reimplement -nofunction argument scripts: kernel-doc: fix troubles with line counts scripts: kernel-doc: use a less pedantic markup for funcs on Sphinx 3.x scripts: kernel-doc: make it more compatible with Sphinx 3.x Revert "kernel-doc: Use c:struct for Sphinx 3.0 and later" Revert "scripts/kerneldoc: For Sphinx 3 use c:macro for macros with arguments" scripts: kernel-doc: add support for typedef enum kernel-doc: add support for ____cacheline_aligned attribute ... Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
show more ...
|
#
2ecfc065 |
| 10-Dec-2020 |
Peter Maydell <peter.maydell@linaro.org> |
Merge remote-tracking branch 'remotes/armbru/tags/pull-misc-2020-12-10' into staging Miscellaneous patches for 2020-12-10 # gpg: Signature made Thu 10 Dec 2020 16:17:43 GMT # gp
Merge remote-tracking branch 'remotes/armbru/tags/pull-misc-2020-12-10' into staging Miscellaneous patches for 2020-12-10 # gpg: Signature made Thu 10 Dec 2020 16:17:43 GMT # gpg: using RSA key 354BC8B3D7EB2A6B68674E5F3870B400EB918653 # gpg: issuer "armbru@redhat.com" # gpg: Good signature from "Markus Armbruster <armbru@redhat.com>" [full] # gpg: aka "Markus Armbruster <armbru@pond.sub.org>" [full] # Primary key fingerprint: 354B C8B3 D7EB 2A6B 6867 4E5F 3870 B400 EB91 8653 * remotes/armbru/tags/pull-misc-2020-12-10: docs/devel/writing-qmp-commands.txt: Fix docs qapi: Normalize version references x.y.0 to just x.y Tweak a few "Parameter 'NAME' expects THING" error message qom: Improve {qom,device}-list-properties error messages qga: Tweak a guest-shutdown error message qga: Replace an unreachable error by abort() ui: Tweak a client_migrate_info error message ui: Improve a client_migrate_info error message ui: Improve some set_passwd, expire_password error messages block: Improve some block-commit, block-stream error messages qerror: Eliminate QERR_ macros used in just one place qerror: Drop unused QERR_ macros Clean up includes Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
show more ...
|
Revision tags: v5.2.0 |
|
#
9bc6e893 |
| 18-Nov-2020 |
Markus Armbruster <armbru@redhat.com> |
qapi: Normalize version references x.y.0 to just x.y We use x.y most of the time, and x.y.0 sometimes. Normalize for consistency. Reported-by: Eduardo Habkost <ehabkost@redhat.
qapi: Normalize version references x.y.0 to just x.y We use x.y most of the time, and x.y.0 sometimes. Normalize for consistency. Reported-by: Eduardo Habkost <ehabkost@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20201118064158.3359056-1-armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
show more ...
|
#
b23317ee |
| 01-Oct-2020 |
Peter Maydell <peter.maydell@linaro.org> |
Merge remote-tracking branch 'remotes/kraxel/tags/microvm-20200930-pull-request' into staging microvm: add pcie support. # gpg: Signature made Wed 30 Sep 2020 18:48:41 BST # gpg
Merge remote-tracking branch 'remotes/kraxel/tags/microvm-20200930-pull-request' into staging microvm: add pcie support. # gpg: Signature made Wed 30 Sep 2020 18:48:41 BST # gpg: using RSA key 4CB6D8EED3E87138 # gpg: Good signature from "Gerd Hoffmann (work) <kraxel@redhat.com>" [full] # gpg: aka "Gerd Hoffmann <gerd@kraxel.org>" [full] # gpg: aka "Gerd Hoffmann (private) <kraxel@gmail.com>" [full] # Primary key fingerprint: A032 8CFF B93A 17A7 9901 FE7D 4CB6 D8EE D3E8 7138 * remotes/kraxel/tags/microvm-20200930-pull-request: tests/acpi: update expected data files acpi/gpex: no reason to use a method for _CRS tests/acpi: add microvm pcie test tests/acpi: factor out common microvm test setup tests/acpi: add empty tests/data/acpi/microvm/DSDT.pcie file tests/acpi: allow updates for expected data files microvm/pcie: add 64bit mmio window microvm: add pcie support microvm: add irq table arm: use acpi_dsdt_add_gpex acpi: add acpi_dsdt_add_gpex move MemMapEntry Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
show more ...
|
#
cbba3dc6 |
| 30-Sep-2020 |
Peter Maydell <peter.maydell@linaro.org> |
Merge remote-tracking branch 'remotes/mst/tags/for_upstream' into staging acpi: unit test This just adds a unit test for previously merged functionality. A bit unusual, but we h
Merge remote-tracking branch 'remotes/mst/tags/for_upstream' into staging acpi: unit test This just adds a unit test for previously merged functionality. A bit unusual, but we have a contribitor under a deadline, let's be nice and merge the unit test right away - does no harm. Hopefully this won't be a beginning of a trend ... Signed-off-by: Michael S. Tsirkin <mst@redhat.com> # gpg: Signature made Wed 30 Sep 2020 09:13:13 BST # gpg: using RSA key 5D09FD0871C8F85B94CA8A0D281F0DB8D28D5469 # gpg: issuer "mst@redhat.com" # gpg: Good signature from "Michael S. Tsirkin <mst@kernel.org>" [full] # gpg: aka "Michael S. Tsirkin <mst@redhat.com>" [full] # Primary key fingerprint: 0270 606B 6F3C DF3D 0B17 0970 C350 3912 AFBE 8E67 # Subkey fingerprint: 5D09 FD08 71C8 F85B 94CA 8A0D 281F 0DB8 D28D 5469 * remotes/mst/tags/for_upstream: tests/acpi: add DSDT.hpbrroot DSDT table blob to test global i440fx hotplug tests/acpi: unit test exercising global pci hotplug off for i440fx Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
show more ...
|
#
61c7f987 |
| 13-Sep-2020 |
Philippe Mathieu-Daudé <philmd@redhat.com> |
qapi: Extract PCI commands to 'pci.json' Only qemu-system-FOO and qemu-storage-daemon provide QMP monitors, therefore such declarations and definitions are irrelevant for user-mode e
qapi: Extract PCI commands to 'pci.json' Only qemu-system-FOO and qemu-storage-daemon provide QMP monitors, therefore such declarations and definitions are irrelevant for user-mode emulation. Extracting the PCI commands to their own schema reduces the size of the qapi-misc* headers generated, and pulls less QAPI-generated code into user-mode. Suggested-by: Markus Armbruster <armbru@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Acked-by: Paolo Bonzini <pbonzini@redhat.com> Signed-off-by: Philippe Mathieu-Daudé <philmd@redhat.com> Message-Id: <20200913195348.1064154-9-philmd@redhat.com> [Commit message tweaked] Signed-off-by: Markus Armbruster <armbru@redhat.com>
show more ...
|