[v2,0/9] qapi: convert example sections to qmp-example rST directives

Message

John Snow July 17, 2024, 2:13 a.m. UTC

This patchset focuses on converting example sections to rST directives
using a new `.. qmp-example::` directive.

V2:
 - Rebased on origin/master; converted one more example
 - Fixed (most?) minor nits from last review
 - Didn't address lack of newline in text mode or enhanced lexer (yet)

Changes since this was split out from the prior series:

- Harmonie updated the CSS for the example block section.
  I think it's really tidy now! Thanks Harmonie!
- Dependence on SphinxDirective was removed, but it will likely
  re-appear in the next series anyway.
- qapi-code-gen.rst was updated with a section on how to write examples.
- Various minor tweaks to comments, commit messages, docs, etc.

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

John Snow (8):
  [DO-NOT-MERGE]: Add some ad-hoc linting helpers.
  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           |  58 +++++++++--
 docs/sphinx-static/theme_overrides.css |  49 ++++++++++
 docs/sphinx/qapidoc.py                 | 130 ++++++++++++++++++++++---
 qapi/acpi.json                         |   4 +-
 qapi/block-core.json                   |  88 +++++++++--------
 qapi/block.json                        |  57 ++++++-----
 qapi/char.json                         |  24 +++--
 qapi/control.json                      |   8 +-
 qapi/dump.json                         |   8 +-
 qapi/machine-target.json               |   2 +-
 qapi/machine.json                      |  68 +++++++------
 qapi/migration.json                    |  90 +++++++++--------
 qapi/misc-target.json                  |  22 ++---
 qapi/misc.json                         |  32 +++---
 qapi/net.json                          |  22 +++--
 qapi/pci.json                          |   2 +-
 qapi/qdev.json                         |  10 +-
 qapi/qom.json                          |  16 +--
 qapi/replay.json                       |   8 +-
 qapi/rocker.json                       |   8 +-
 qapi/run-state.json                    |  32 +++---
 qapi/tpm.json                          |   6 +-
 qapi/trace.json                        |   4 +-
 qapi/transaction.json                  |   2 +-
 qapi/ui.json                           |  45 ++++-----
 qapi/vfio.json                         |   2 +-
 qapi/virtio.json                       |  45 ++++++---
 qapi/yank.json                         |   4 +-
 scripts/qapi-lint.sh                   |  61 ++++++++++++
 scripts/qapi/Makefile                  |   5 +
 scripts/qapi/parser.py                 |  10 +-
 tests/qapi-schema/doc-good.json        |  19 ++--
 tests/qapi-schema/doc-good.out         |  26 +++--
 tests/qapi-schema/doc-good.txt         |  23 ++---
 34 files changed, 662 insertions(+), 328 deletions(-)
 create mode 100755 scripts/qapi-lint.sh
 create mode 100644 scripts/qapi/Makefile

Comments

Markus Armbruster July 17, 2024, 10:47 a.m. UTC | #1

John Snow <[e-mail]> writes:

> This patchset focuses on converting example sections to rST directives
> using a new `.. qmp-example::` directive.

Queued, thanks!

John Snow July 17, 2024, 8:13 p.m. UTC | #2

On Wed, Jul 17, 2024, 6:47 AM Markus Armbruster <[e-mail]> wrote:

> John Snow <[e-mail]> writes:
>
> > This patchset focuses on converting example sections to rST directives
> > using a new `.. qmp-example::` directive.
>
> Queued, thanks!
>

Yay!

>