[0/8] qapi: convert example sections to qmp-example rST directives

Message

John Snow July 3, 2024, 9:01 p.m. UTC

GitLab: https://gitlab.com/jsnow/qemu/-/pipelines/1359714660

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

It is based on what I *assume* will be Markus' next pull request that
covers note conversion. Pull these patches from GitLab directly if
that's too annoying:
https://gitlab.com/jsnow/qemu/-/commits/sphinx-domain-prereqs-examples

It is also annoyingly the case that both Markus' next pull request and
this series conflicts with a separate series I sent out, "docs/python:
bump minimum Sphinx version" - so it's extremely likely I'll need to
rebase and respin this series depending on what goes in and in what
order. Ah well...

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 (7):
  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                 | 156 +++++++++++++++++++++----
 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                          |  20 ++--
 qapi/pci.json                          |   2 +-
 qapi/qdev.json                         |  10 +-
 qapi/qom.json                          |  16 +--
 qapi/replay.json                       |   8 +-
 qapi/rocker.json                       |   8 +-
 qapi/run-state.json                    |  30 ++---
 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/parser.py                 |  10 +-
 tests/qapi-schema/doc-good.json        |  19 +--
 tests/qapi-schema/doc-good.out         |  26 +++--
 tests/qapi-schema/doc-good.txt         |  23 ++--
 32 files changed, 605 insertions(+), 341 deletions(-)

Comments

Markus Armbruster July 9, 2024, 4:55 p.m. UTC | #1

You achieved a clean & consistent look for notes and examples in the
browser.  Love it!