[v3,00/63] docs: Add new QAPI transmogrifier

Message

John Snow March 11, 2025, 3:41 a.m. UTC

This series is a "minimum viable" version of the new QAPI documentation
system. It does the bare minimum under the new framework, saving the
fancy features like the inliner for later. This version does add
cross-references for all QAPI definitions and a shiny new QAPI Index.

Patches 3-31 implement the qapi_domain extension.
Patches 32-59 implement the qapidoc "Transmogrifier".

Known shortcomings in this series:

- Some ifcond information (features, members) is still not displayed.
- No QAPI namespace support ... yet. So we can't enable it for QMP, QGA
  and QSD simultaneously just yet. It's nearly complete.

v3:

- Moved a few more methods from QAPIObject to QAPIDescription
- Implemented most of the rest of Markus' feedback.

v2:

- Did you know that my computer just shut off the moment I started
  sending the patchset? Just a hard off. Wow!
- Refactored QAPIObject class so that QAPIModule uses more of
Sphinx's ObjectDescription class, which means less fooling around with
re-parsing Sphinx standard options.
- Removed test document, flipped switch on the real QMP manual.
- Undocumented members have been re-added. I think that's new for this version!
- Removed some inliner branch code that snuck into the "validate info
  fields" patch.
- Lots of Markus' feedback, and misc changes.

"v1":

- @foo is processed into ``foo`
- "The members of ..." messages have been temporarily re-added until we
  can smooth over the inliner.
- This series runs under Sphinx 3.4.3 to Sphinx 8.2.0 inclusive. It
  truly is a Christmas miracle. (please clap)
- This series now fully type checks and lint checks under Sphinx 8.2.0,
  but may not type check under earlier Sphinx versions. Achieving this
  alone, nevermind in conjunction with the above, was a literal
  herculean labor.

John Snow (63):
  do-not-merge
  qapi: shush pylint up
  docs/sphinx: create QAPI domain extension stub
  docs/sphinx: add compat.py module and nested_parse helper
  docs/qapi-domain: add QAPI domain object registry
  docs/qapi-domain: add QAPI index
  docs/qapi-domain: add resolve_any_xref()
  docs/qapi-domain: add QAPI xref roles
  docs/qapi-domain: add compatibility node classes
  docs/qapi-domain: Add QAPIDescription abstract class
  docs/qapi-domain: add qapi:module directive
  docs/qapi-domain: add QAPIObject class
  docs/qapi-domain: add qapi:command directive
  docs/qapi-domain: add :since: directive option
  docs/qapi-domain: add "Arguments:" field lists
  docs/qapi-domain: add "Features:" field lists
  docs/qapi-domain: add "Errors:" field lists
  docs/qapi-domain: add "Return:" field lists
  docs/qapi-domain: add qapi:enum directive
  docs/qapi-domain: add qapi:alternate directive
  docs/qapi-domain: add qapi:event directive
  docs/qapi-domain: add qapi:object directive
  docs/qapi-domain: add :deprecated: directive option
  docs/qapi-domain: add :unstable: directive option
  docs/qapi-domain: add :ifcond: directive option
  docs/qapi-domain: add warnings for malformed field lists
  docs/qapi-domain: add type cross-refs to field lists
  docs/qapi-domain: add CSS styling
  docs/qapi-domain: add XREF compatibility goop for Sphinx < 4.1
  docs/qapi-domain: warn when QAPI domain xrefs fail to resolve
  docs/qapi-domain: Fix error context reporting in Sphinx 5.x and 6.x
  qapi/parser: adjust info location for doc body section
  qapi: clean up encoding of section kinds
  qapi/schema: add __repr__ to QAPIDoc.Section
  docs/qapidoc: add transmogrifier stub
  docs/qapidoc: split old implementation into qapidoc_legacy.py
  docs/qapidoc: Fix static typing on qapidoc.py
  do-not-merge
  docs/qapidoc: add transmogrifier class stub
  docs/qapidoc: add visit_module() method
  qapi/source: allow multi-line QAPISourceInfo advancing
  docs/qapidoc: add visit_freeform() method
  docs/qapidoc: add preamble() method
  docs/qapidoc: add visit_paragraph() method
  docs/qapidoc: add visit_errors() method
  docs/qapidoc: add format_type() method
  docs/qapidoc: add add_field() and generate_field() helper methods
  docs/qapidoc: add visit_feature() method
  docs/qapidoc: prepare to record entity being transmogrified
  docs/qapidoc: add visit_returns() method
  docs/qapidoc: add visit_member() method
  docs/qapidoc: add visit_sections() method
  docs/qapidoc: add visit_entity()
  docs/qapidoc: implement transmogrify() method
  docs/qapidoc: process @foo into ``foo``
  docs/qapidoc: add intermediate output debugger
  docs/qapidoc: Add "the members of" pointers
  docs/qapidoc: generate entries for undocumented members
  qapi/parser: add undocumented stub members to all_sections
  docs: disambiguate cross-references
  docs: enable qapidoc transmogrifier for QEMU QMP Reference
  docs: add qapi-domain syntax documentation
  MAINTAINERS: Add jsnow as maintainer for Sphinx documentation

 MAINTAINERS                            |   1 +
 docs/conf.py                           |  18 +-
 docs/devel/codebase.rst                |   6 +-
 docs/devel/index-build.rst             |   1 +
 docs/devel/qapi-domain.rst             | 670 ++++++++++++++++++
 docs/glossary.rst                      |  10 +-
 docs/interop/qemu-qmp-ref.rst          |   1 +
 docs/sphinx-static/theme_overrides.css |  98 ++-
 docs/sphinx/compat.py                  | 230 ++++++
 docs/sphinx/qapi_domain.py             | 931 ++++++++++++++++++++++++
 docs/sphinx/qapidoc.py                 | 941 +++++++++++++------------
 docs/sphinx/qapidoc_legacy.py          | 440 ++++++++++++
 qapi/qapi-schema.json                  |   2 +
 scripts/qapi-lint.sh                   |  57 ++
 scripts/qapi/backend.py                |   2 +
 scripts/qapi/main.py                   |   8 +-
 scripts/qapi/parser.py                 | 123 +++-
 scripts/qapi/source.py                 |   4 +-
 tests/qapi-schema/doc-good.out         |  10 +-
 tests/qapi-schema/test-qapi.py         |   2 +-
 20 files changed, 3070 insertions(+), 485 deletions(-)
 create mode 100644 docs/devel/qapi-domain.rst
 create mode 100644 docs/sphinx/compat.py
 create mode 100644 docs/sphinx/qapi_domain.py
 create mode 100644 docs/sphinx/qapidoc_legacy.py
 create mode 100755 scripts/qapi-lint.sh

Comments

Markus Armbruster March 11, 2025, 8:52 a.m. UTC | #1

John Snow <[e-mail]> writes:

> This series is a "minimum viable" version of the new QAPI documentation
> system. It does the bare minimum under the new framework, saving the
> fancy features like the inliner for later. This version does add
> cross-references for all QAPI definitions and a shiny new QAPI Index.

PATCH 01,02 are not for merge.

> Patches 3-31 implement the qapi_domain extension.

These patches
Acked-by: Markus Armbruster <[e-mail]>

> Patches 32-59 implement the qapidoc "Transmogrifier".

These patches
Acked-by: Markus Armbruster <[e-mail]>
except for PATCH 32-34,41,59, which are R-by instead, and PATCH 38,
which is not for merge.

Queued except for 01,02,38.  Expect a pull request later today.

[...]