John Snow <js...@redhat.com> writes:
> This clarifies sections that are mistaken by the parser as "intro"
> sections to be "details" sections instead.
Impact on output? See notes inline.
>
> Signed-off-by: John Snow <js...@redhat.com>
> ---
> qapi/machine.json | 2 ++
> qapi/migration.json | 4 ++++
> qapi/qom.json | 4 ++++
> qapi/yank.json | 2 ++
> scripts/qapi/parser.py | 8 ++++++++
> 5 files changed, 20 insertions(+)
>
> diff --git a/qapi/machine.json b/qapi/machine.json
> index a6b8795b09e..3c1b397f6cc 100644
> --- a/qapi/machine.json
> +++ b/qapi/machine.json
> @@ -1301,6 +1301,8 @@
> # Return the amount of initially allocated and present hotpluggable
> # (if enabled) memory in bytes.
> #
> +# Details:
> +#
> # .. qmp-example::
> #
> # -> { "execute": "query-memory-size-summary" }
Output unchanged in my testing. Same for the other hunks unless
otherwise noted.
> diff --git a/qapi/migration.json b/qapi/migration.json
> index 43babd1df41..9070a91e655 100644
> --- a/qapi/migration.json
> +++ b/qapi/migration.json
> @@ -1920,6 +1920,8 @@
> #
> # Xen uses this command to notify replication to trigger a checkpoint.
> #
> +# Details:
> +#
> # .. qmp-example::
> #
> # -> { "execute": "xen-colo-do-checkpoint" }
> @@ -1993,6 +1995,8 @@
> #
> # Pause a migration. Currently it only supports postcopy.
> #
> +# Details:
> +#
> # .. qmp-example::
> #
> # -> { "execute": "migrate-pause" }
> diff --git a/qapi/qom.json b/qapi/qom.json
> index 11277d1f84c..5d285ef9239 100644
> --- a/qapi/qom.json
> +++ b/qapi/qom.json
> @@ -729,6 +729,8 @@
> #
> # Properties for memory-backend-shm objects.
> #
> +# Details:
> +#
> # This memory backend supports only shared memory, which is the
> # default.
> #
The paragraphs moves from above to below the auto-generated member
documentation, like this:
@@ -25908,13 +25908,13 @@ If
Properties for memory-backend-shm objects.
-This memory backend supports only shared memory, which is the default.
-
Members
~~~~~~~
The members of "MemoryBackendProperties"
+This memory backend supports only shared memory, which is the default.
+
Since
~~~~~
This is sphinx-build -b text. I don't understand why there is no blank
line between "The members of ... " and the moved paragraph.
> @@ -744,6 +746,8 @@
> #
> # Properties for memory-backend-epc objects.
> #
> +# Details:
> +#
> # The @merge boolean option is false by default with epc
> #
> # The @dump boolean option is false by default with epc
Likewise.
> diff --git a/qapi/yank.json b/qapi/yank.json
> index 30f46c97c98..4d36d21e76a 100644
> --- a/qapi/yank.json
> +++ b/qapi/yank.json
> @@ -104,6 +104,8 @@
> #
> # Returns: list of @YankInstance
> #
> +# Details:
> +#
> # .. qmp-example::
> #
> # -> { "execute": "query-yank" }
> diff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py
> index c5d2b950a82..5890a13b5ba 100644
> --- a/scripts/qapi/parser.py
> +++ b/scripts/qapi/parser.py
> @@ -544,6 +544,14 @@ def _tag_check(what: str) -> None:
> raise QAPIParseError(
> self, 'feature descriptions expected')
> have_tagged = True
> + elif line == 'Details:':
> + _tag_check("Details")
> + self.accept(False)
> + line = self.get_doc_line()
> + while line == '':
> + self.accept(False)
> + line = self.get_doc_line()
> + have_tagged = True
> elif match := self._match_at_name_colon(line):
> # description
> if have_tagged:
