This series focuses primarily on converting our existing QAPI/QMP
documentation to remove special "Note" and "Example" sections in favor
of rST markup for the same.

This is being done primarily to reduce the number of specially parsed
QAPI sections we have in favor of allowing fully arbitrary rST markup
for greater flexibility and freedom in styling the rendered HTML
documentation.

(A tangible side benefit is that the new qapidoc generator has fewer
sections to reason about when it splices inherited documentation
together for the QMP reference manual; docs largely preserve the order
of documentation "as written" instead of needing to splice multiple
separate sections together. A goal of the new generator is to eventually
remove all tagged sections except for "members" and "features".)

Known issues:

- The caption syntax for QMP examples is a little ugly in rendered HTML
  output; My CSS intern wasn't available before publication time to fix
  it ;) -- Will fix with an amendment patch at next opportunity.

Any feedback not implemented should be interpreted as evidence of a
forgetful (rather than a spiteful) mind. Please remind me where
appropriate.

--js

John Snow (13):
  [DO-NOT-MERGE]: Add some ad-hoc linting helpers.
  qapi: linter fixups
  docs/qapidoc: delint a tiny portion of the module
  qapi/parser: preserve indentation in QAPIDoc sections
  qapi/parser: fix comment parsing immediately following a doc block
  docs/qapidoc: fix nested parsing under untagged sections
  qapi: fix non-compliant JSON examples
  qapi: ensure all errors sections are uniformly typset
  qapi: convert "Note" sections to plain rST
  qapi: update prose in note blocks
  qapi: add markup to note blocks
  qapi/parser: don't parse rST markup as section headers
  qapi: convert "Example" sections to rST

 docs/devel/qapi-code-gen.rst                  |  25 +--
 docs/sphinx/qapidoc.py                        | 103 ++++++++----
 qapi/acpi.json                                |   6 +-
 qapi/block-core.json                          | 148 +++++++++-------
 qapi/block.json                               |  62 ++++---
 qapi/char.json                                |  48 ++++--
 qapi/control.json                             |  32 ++--
 qapi/dump.json                                |  14 +-
 qapi/introspect.json                          |   6 +-
 qapi/machine-target.json                      |  29 ++--
 qapi/machine.json                             | 125 ++++++++------
 qapi/migration.json                           | 159 ++++++++++++------
 qapi/misc-target.json                         |  33 ++--
 qapi/misc.json                                | 139 ++++++++-------
 qapi/net.json                                 |  42 +++--
 qapi/pci.json                                 |  11 +-
 qapi/qapi-schema.json                         |   6 +-
 qapi/qdev.json                                |  45 ++---
 qapi/qom.json                                 |  39 +++--
 qapi/replay.json                              |  12 +-
 qapi/rocker.json                              |  30 ++--
 qapi/run-state.json                           |  63 ++++---
 qapi/sockets.json                             |  10 +-
 qapi/stats.json                               |  22 +--
 qapi/tpm.json                                 |   9 +-
 qapi/trace.json                               |   6 +-
 qapi/transaction.json                         |  13 +-
 qapi/ui.json                                  |  93 +++++-----
 qapi/vfio.json                                |   3 +-
 qapi/virtio.json                              |  50 +++---
 qapi/yank.json                                |   6 +-
 qga/qapi-schema.json                          |  48 +++---
 scripts/qapi-lint.sh                          |  59 +++++++
 scripts/qapi/Makefile                         |   5 +
 scripts/qapi/introspect.py                    |   8 +-
 scripts/qapi/parser.py                        |  40 ++++-
 scripts/qapi/schema.py                        |   6 +-
 scripts/qapi/visit.py                         |   5 +-
 tests/qapi-schema/doc-empty-section.err       |   2 +-
 tests/qapi-schema/doc-empty-section.json      |   2 +-
 tests/qapi-schema/doc-good.json               |  21 ++-
 tests/qapi-schema/doc-good.out                |  62 ++++---
 tests/qapi-schema/doc-good.txt                |  31 ++--
 .../qapi-schema/doc-interleaved-section.json  |   2 +-
 44 files changed, 1036 insertions(+), 644 deletions(-)
 create mode 100755 scripts/qapi-lint.sh
 create mode 100644 scripts/qapi/Makefile

-- 
2.44.0

You asked for a summary of my review findings.  Here it is:

* PATCH 01: DO-NOT-MERGE, not reviewed

* PATCH 02, 05..07, 10..12: R-by or A-by

* PATCH 03: R-by with straightforward minor adjustments

* PATCH 04, 08: R-by with commit message and doc tweaks

* PATCH 09:

  - Commit message tweaks

  - You convert "Note:" even in free-form doc, where it isn't
    recognized; separate patch or mention in commit message

  - You silently move one note; don't, separate patch, or mention in
    commit message

  - Tweak doc-interleaved-section.json

  - A few more notes need to start with a capital letter and / or end
    with a period

  - I don't like the indentation change

* PATCH 12: Want a positive test

* PATCH 13:

  - One hunk should be squashed into PATCH 09

  - Accidentally duplicated example should be dropped

  - You convert "Example:" even in free-form doc, where it isn't
    recognized; separate patch or mention in commit message

  - Sphinx doesn't recognize a .. code-block: directive in doc-good.json

  - doc-good.txt loses "Example"

  - Generated HTML looks somehwat ugly

Feel free to leave reverting indentation changes to me.  Same for
starting notes with a capital letter and ending them with a period.

I'm willing to accept ugly HTML along with a promise of future
improvement :)

On Tue, Jun 18, 2024 at 08:29:59PM -0400, John Snow wrote:
> This series focuses primarily on converting our existing QAPI/QMP
> documentation to remove special "Note" and "Example" sections in favor
> of rST markup for the same.
> 
> This is being done primarily to reduce the number of specially parsed
> QAPI sections we have in favor of allowing fully arbitrary rST markup
> for greater flexibility and freedom in styling the rendered HTML
> documentation.
> 
> (A tangible side benefit is that the new qapidoc generator has fewer
> sections to reason about when it splices inherited documentation
> together for the QMP reference manual; docs largely preserve the order
> of documentation "as written" instead of needing to splice multiple
> separate sections together. A goal of the new generator is to eventually
> remove all tagged sections except for "members" and "features".)
> 
> Known issues:
> 
> - The caption syntax for QMP examples is a little ugly in rendered HTML
>   output; My CSS intern wasn't available before publication time to fix
>   it ;) -- Will fix with an amendment patch at next opportunity.
> 
> Any feedback not implemented should be interpreted as evidence of a
> forgetful (rather than a spiteful) mind. Please remind me where
> appropriate.
> 
> --js

virtio things:

Reviewed-by: Michael S. Tsirkin <mst@redhat.com>


> John Snow (13):
>   [DO-NOT-MERGE]: Add some ad-hoc linting helpers.
>   qapi: linter fixups
>   docs/qapidoc: delint a tiny portion of the module
>   qapi/parser: preserve indentation in QAPIDoc sections
>   qapi/parser: fix comment parsing immediately following a doc block
>   docs/qapidoc: fix nested parsing under untagged sections
>   qapi: fix non-compliant JSON examples
>   qapi: ensure all errors sections are uniformly typset
>   qapi: convert "Note" sections to plain rST
>   qapi: update prose in note blocks
>   qapi: add markup to note blocks
>   qapi/parser: don't parse rST markup as section headers
>   qapi: convert "Example" sections to rST
> 
>  docs/devel/qapi-code-gen.rst                  |  25 +--
>  docs/sphinx/qapidoc.py                        | 103 ++++++++----
>  qapi/acpi.json                                |   6 +-
>  qapi/block-core.json                          | 148 +++++++++-------
>  qapi/block.json                               |  62 ++++---
>  qapi/char.json                                |  48 ++++--
>  qapi/control.json                             |  32 ++--
>  qapi/dump.json                                |  14 +-
>  qapi/introspect.json                          |   6 +-
>  qapi/machine-target.json                      |  29 ++--
>  qapi/machine.json                             | 125 ++++++++------
>  qapi/migration.json                           | 159 ++++++++++++------
>  qapi/misc-target.json                         |  33 ++--
>  qapi/misc.json                                | 139 ++++++++-------
>  qapi/net.json                                 |  42 +++--
>  qapi/pci.json                                 |  11 +-
>  qapi/qapi-schema.json                         |   6 +-
>  qapi/qdev.json                                |  45 ++---
>  qapi/qom.json                                 |  39 +++--
>  qapi/replay.json                              |  12 +-
>  qapi/rocker.json                              |  30 ++--
>  qapi/run-state.json                           |  63 ++++---
>  qapi/sockets.json                             |  10 +-
>  qapi/stats.json                               |  22 +--
>  qapi/tpm.json                                 |   9 +-
>  qapi/trace.json                               |   6 +-
>  qapi/transaction.json                         |  13 +-
>  qapi/ui.json                                  |  93 +++++-----
>  qapi/vfio.json                                |   3 +-
>  qapi/virtio.json                              |  50 +++---
>  qapi/yank.json                                |   6 +-
>  qga/qapi-schema.json                          |  48 +++---
>  scripts/qapi-lint.sh                          |  59 +++++++
>  scripts/qapi/Makefile                         |   5 +
>  scripts/qapi/introspect.py                    |   8 +-
>  scripts/qapi/parser.py                        |  40 ++++-
>  scripts/qapi/schema.py                        |   6 +-
>  scripts/qapi/visit.py                         |   5 +-
>  tests/qapi-schema/doc-empty-section.err       |   2 +-
>  tests/qapi-schema/doc-empty-section.json      |   2 +-
>  tests/qapi-schema/doc-good.json               |  21 ++-
>  tests/qapi-schema/doc-good.out                |  62 ++++---
>  tests/qapi-schema/doc-good.txt                |  31 ++--
>  .../qapi-schema/doc-interleaved-section.json  |   2 +-
>  44 files changed, 1036 insertions(+), 644 deletions(-)
>  create mode 100755 scripts/qapi-lint.sh
>  create mode 100644 scripts/qapi/Makefile
> 
> -- 
> 2.44.0
>