[Qemu-commits] [qemu/qemu] d98884: qapi: Reject section markup in definition document...

[Peter Maydell]

  Branch: refs/heads/master
  Home:   https://github.com/qemu/qemu
  Commit: d98884b75df3676f94d93fbaf6372ca705dc2aee
      
https://github.com/qemu/qemu/commit/d98884b75df3676f94d93fbaf6372ca705dc2aee
  Author: Markus Armbruster <armbru@redhat.com>
  Date:   2020-09-07 (Mon, 07 Sep 2020)

  Changed paths:
    M docs/devel/qapi-code-gen.txt
    M scripts/qapi/parser.py
    M tests/qapi-schema/doc-bad-section.err
    M tests/qapi-schema/doc-bad-section.json
    M tests/qapi-schema/doc-bad-section.out

  Log Message:
  -----------
  qapi: Reject section markup in definition documentation

Section markup in definition documentation makes no sense and can
produce invalid Texinfo.  Reject.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20200320091805.5585-2-armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>


  Commit: dcdc07a97cbe57369d75077c9d3ea035f8c5f483
      
https://github.com/qemu/qemu/commit/dcdc07a97cbe57369d75077c9d3ea035f8c5f483
  Author: Markus Armbruster <armbru@redhat.com>
  Date:   2020-09-07 (Mon, 07 Sep 2020)

  Changed paths:
    M scripts/qapi/parser.py
    M tests/qapi-schema/doc-good.out

  Log Message:
  -----------
  qapi: Make section headings start a new doc comment block

Our current QAPI doc-comment markup allows section headers (introduced
with a leading '=' or '==') anywhere in a free-form documentation
comment.  This works for Texinfo because the generator simply prints a
Texinfo section command at that point in the output stream.  For rST
generation, since we're assembling a tree of docutils nodes, this is
awkward because a new section implies starting a new section node at
the top level of the tree and generating text into there.

Make section headers start a new free-form documentation block, so the
future rST document generator doesn't have to look at every line in
free-form blocks and handle headings in odd places.

This change makes no difference to the generated Texinfo.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20200320091805.5585-3-armbru@redhat.com>


  Commit: 76dd0f84974582311e4f5a763db68dea388d38b5
      
https://github.com/qemu/qemu/commit/76dd0f84974582311e4f5a763db68dea388d38b5
  Author: Peter Maydell <peter.maydell@linaro.org>
  Date:   2020-09-07 (Mon, 07 Sep 2020)

  Changed paths:
    M qapi/migration.json

  Log Message:
  -----------
  qapi/migration.json: Fix indentation

Commits 6a9ad1542065ca0bd54c6 and 9004db48c080632aef23 added some
new text to qapi/migration.json which doesn't fit the stricter
indentation requirements imposed by the rST documentation generator.
Reindent those lines to the new standard.

Reviewed-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Message-Id: <20200810195019.25427-2-peter.maydell@linaro.org>
Signed-off-by: Markus Armbruster <armbru@redhat.com>


  Commit: b2f1c13c31af2db759b7545cd8e8c525d6cb2e13
      
https://github.com/qemu/qemu/commit/b2f1c13c31af2db759b7545cd8e8c525d6cb2e13
  Author: Peter Maydell <peter.maydell@linaro.org>
  Date:   2020-09-07 (Mon, 07 Sep 2020)

  Changed paths:
    M qapi/audio.json
    M qapi/block-core.json
    M qapi/control.json
    M qapi/machine.json
    M qapi/migration.json
    M qapi/misc.json
    M qapi/net.json

  Log Message:
  -----------
  qapi: Fix indentation, again

In commit 26ec4e53f2 and similar commits we fixed the indentation
for doc comments in our qapi json files to follow a new stricter
standard for indentation, which permits only:
    @arg: description line 1
          description line 2

or:
    @arg:
    line 1
    line 2

Unfortunately since we didn't manage to get the script changes that
enforced the new style in, a variety of commits (eg df4097aeaf71,
2e4457032105) introduced new doc text which doesn't follow the new
stricter rules for indentation on multi-line doc comments.  Bring
those into line with the new rules.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Message-Id: <20200810195019.25427-3-peter.maydell@linaro.org>
Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
Signed-off-by: Markus Armbruster <armbru@redhat.com>


  Commit: 6b306786cafd6ff939f1c831f0065c136105dca7
      
https://github.com/qemu/qemu/commit/6b306786cafd6ff939f1c831f0065c136105dca7
  Author: Peter Maydell <peter.maydell@linaro.org>
  Date:   2020-09-07 (Mon, 07 Sep 2020)

  Changed paths:
    M qapi/block-core.json

  Log Message:
  -----------
  qapi/block-core.json: Fix nbd-server-start docs

Commit eed8b6917832 added some new text to the nbd-server-start
documentation in the wrong place.  Since this is after the 'Returns:'
line it's parsed as if it were part of the documentation of the
"Returns:' information.  Move it up to join the rest of the
"documentation of the type as a whole" doc text.

This doesn't look odd in the current HTML rendering, but the
new QAPI-to-rST handling will complain about the indent level
of the lines not matching up with the 'Returns:' line.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Message-Id: <20200810195019.25427-4-peter.maydell@linaro.org>
Reviewed-by: Richard Henderson <richard.henderson@linaro.org>
Signed-off-by: Markus Armbruster <armbru@redhat.com>


  Commit: 6779038537360e957dbded830f76b08ef5070161
      
https://github.com/qemu/qemu/commit/6779038537360e957dbded830f76b08ef5070161
  Author: Peter Maydell <peter.maydell@linaro.org>
  Date:   2020-09-08 (Tue, 08 Sep 2020)

  Changed paths:
    M docs/devel/qapi-code-gen.txt
    M qapi/audio.json
    M qapi/block-core.json
    M qapi/control.json
    M qapi/machine.json
    M qapi/migration.json
    M qapi/misc.json
    M qapi/net.json
    M scripts/qapi/parser.py
    M tests/qapi-schema/doc-bad-section.err
    M tests/qapi-schema/doc-bad-section.json
    M tests/qapi-schema/doc-bad-section.out
    M tests/qapi-schema/doc-good.out

  Log Message:
  -----------
  Merge remote-tracking branch 'remotes/armbru/tags/pull-qapi-2020-09-08' into 
staging

QAPI patches patches for 2020-09-08

# gpg: Signature made Tue 08 Sep 2020 07:06:52 BST
# 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-qapi-2020-09-08:
  qapi/block-core.json: Fix nbd-server-start docs
  qapi: Fix indentation, again
  qapi/migration.json: Fix indentation
  qapi: Make section headings start a new doc comment block
  qapi: Reject section markup in definition documentation

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>


Compare: https://github.com/qemu/qemu/compare/b95ba83fc56e...677903853736