[v2,00/21] qapi: convert "Note" and "Example" sections to rST

Message

John Snow June 26, 2024, 10:21 p.m. UTC

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".)

V2:
 - Lotsa stuff :{
 - Added new example box styling and sphinx directive macro
 - Addressed... most? list feedback. (But not the indent split.)

Known issues:

- The Example boxes are styled a little wonkily if prose follows the
  code-block instead of precedes it, fixup will be tomorrow.

--js

Harmonie Snow (1):
  docs/sphinx: add CSS styling for qmp-example directive

John Snow (20):
  [DO-NOT-MERGE]: Add some ad-hoc linting helpers.
  qapi: linter fixups
  docs/qapidoc: remove unused intersperse function
  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: nail down convention that Errors sections are lists
  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
  docs/qapidoc: factor out do_parse()
  docs/qapidoc: create qmp-example directive
  docs/qapidoc: add QMP highlighting to annotated qmp-example blocks
  qapi: convert "Example" sections without titles
  qapi: convert "Example" sections with titles
  qapi: convert "Example" sections with longer prose
  qapi: remove "Example" doc section

 docs/devel/qapi-code-gen.rst                  |  25 +-
 docs/sphinx-static/theme_overrides.css        |  46 ++++
 docs/sphinx/qapidoc.py                        | 258 +++++++++++++-----
 qapi/acpi.json                                |   4 +-
 qapi/block-core.json                          | 116 ++++----
 qapi/block.json                               |  59 ++--
 qapi/char.json                                |  36 ++-
 qapi/control.json                             |  28 +-
 qapi/dump.json                                |  10 +-
 qapi/introspect.json                          |   6 +-
 qapi/machine-target.json                      |  28 +-
 qapi/machine.json                             | 117 ++++----
 qapi/migration.json                           | 104 +++----
 qapi/misc-target.json                         |  22 +-
 qapi/misc.json                                | 123 +++++----
 qapi/net.json                                 |  32 ++-
 qapi/pci.json                                 |  10 +-
 qapi/qdev.json                                |  40 +--
 qapi/qom.json                                 |  33 ++-
 qapi/replay.json                              |   8 +-
 qapi/rocker.json                              |  26 +-
 qapi/run-state.json                           |  48 ++--
 qapi/sockets.json                             |  10 +-
 qapi/stats.json                               |  22 +-
 qapi/tpm.json                                 |   6 +-
 qapi/trace.json                               |   4 +-
 qapi/transaction.json                         |  12 +-
 qapi/ui.json                                  |  76 +++---
 qapi/vfio.json                                |   2 +-
 qapi/virtio.json                              |  57 ++--
 qapi/yank.json                                |   4 +-
 qga/qapi-schema.json                          |  48 ++--
 scripts/qapi-lint.sh                          |  61 +++++
 scripts/qapi/Makefile                         |   5 +
 scripts/qapi/introspect.py                    |   8 +-
 scripts/qapi/parser.py                        |  38 ++-
 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               |  28 +-
 tests/qapi-schema/doc-good.out                |  61 +++--
 tests/qapi-schema/doc-good.txt                |  36 ++-
 .../qapi-schema/doc-interleaved-section.json  |   2 +-
 44 files changed, 1010 insertions(+), 664 deletions(-)
 create mode 100755 scripts/qapi-lint.sh
 create mode 100644 scripts/qapi/Makefile