Re: [PATCH 00/13] qapi: convert "Note" and "Example" sections to rST

[Michael S. Tsirkin]

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
>