Skip to content

qapi: convert "Note" and "Example" sections to rST

John Snow qemu-devel 2 versions – In review

Get series with b4
b4 am [email protected]

Versions newest first · linked by author and title

  1. v2 Latest21 patches 22 repliesIn review
  2. v113 patches 39 repliesSuperseded

Changes in v2 from the cover letter

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

Patches in v2 No applies recorded yet

#Subject and filesSizeRepliesApplied
1/21: Add some ad-hoc linting helpers.scripts/qapi-lint.sh scripts/qapi/Makefile+66 -00 replies
2/21qapi: linter fixupsscripts/qapi/introspect.py scripts/qapi/schema.py scripts/qapi/visit.py+10 -90 replies
3/21docs/qapidoc: remove unused intersperse functiondocs/sphinx/qapidoc.py+0 -104 replies
4/21docs/qapidoc: delint a tiny portion of the moduledocs/sphinx/qapidoc.py+37 -252 replies
5/21qapi/parser: preserve indentation in QAPIDoc sectionsdocs/sphinx/qapidoc.py scripts/qapi/parser.py tests/qapi-schema/doc-good.out+40 -234 replies
6/21qapi/parser: fix comment parsing immediately following a doc blockscripts/qapi/parser.py tests/qapi-schema/doc-good.json+3 -10 replies
7/21docs/qapidoc: fix nested parsing under untagged sectionsdocs/sphinx/qapidoc.py+11 -54 replies
8/21qapi: fix non-compliant JSON examplesqapi/control.json qapi/machine.json qapi/migration.json +4 more+11 -90 replies
9/21qapi: nail down convention that Errors sections are listsdocs/devel/qapi-code-gen.rst qapi/transaction.json+8 -10 replies
10/21qapi: convert "Note" sections to plain rSTdocs/devel/qapi-code-gen.rst qapi/block-core.json qapi/block.json +27 more+260 -2523 replies
11/21qapi: update prose in note blocksqapi/block-core.json qga/qapi-schema.json+3 -30 replies
12/21qapi: add markup to note blocksqapi/control.json qapi/misc.json qapi/qdev.json +3 more+10 -100 replies
13/21qapi/parser: don't parse rST markup as section headersscripts/qapi/parser.py tests/qapi-schema/doc-good.json tests/qapi-schema/doc-good.out +1 more+16 -21 reply
14/21docs/qapidoc: factor out do_parse()docs/sphinx/qapidoc.py+35 -292 replies
15/21docs/qapidoc: create qmp-example directivedocs/sphinx/qapidoc.py+58 -22 replies
16/21docs/qapidoc: add QMP highlighting to annotated qmp-example blocksdocs/sphinx/qapidoc.py+49 -40 replies
17/21docs/sphinx: add CSS styling for qmp-example directivedocs/sphinx-static/theme_overrides.css+46 -00 replies
18/21qapi: convert "Example" sections without titlesqapi/acpi.json qapi/block-core.json qapi/block.json +22 more+216 -2020 replies
19/21qapi: convert "Example" sections with titlesqapi/block-core.json qapi/block.json qapi/migration.json +3 more+52 -480 replies
20/21qapi: convert "Example" sections with longer proseqapi/block.json qapi/machine.json qapi/migration.json +1 more+59 -280 replies
21/21qapi: remove "Example" doc sectiondocs/devel/qapi-code-gen.rst scripts/qapi/parser.py tests/qapi-schema/doc-good.json +2 more+56 -370 replies

Reviews trailers per patch

13 of 21 patches have a Reviewed-by or Acked-by.

PatchMarkus ArmbrusterStefan Hajnoczi
1/21
2/21R-b
3/21R-b R-b
4/21R-b
5/21R-b
6/21R-b
7/21A-b
8/21R-b
9/21R-b
10/21R-b A-b
11/21R-b
12/21R-b
13/21R-b
14/21R-b
15/21
16/21
17/21
18/21
19/21
20/21
21/21

Trailers given in replies are filled; those carried in the patches from earlier versions are outlined with dashes.

Read the v2 thread

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

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
Signature · 1 line
2.45.0