[v2,00/62] docs: Add new QAPI transmogrifier

Message

John Snow March 9, 2025, 8:34 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 nice
features for later.

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

Known shortcomings in this series:

- Some ifcond information 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.
- Didn't finish addressing all of Markus' feedback, but needed to get
  another spin out on the list ASAP.

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 (62):
  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 ObjectDescription 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: expand tags to all doc sections
  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

 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             | 926 ++++++++++++++++++++++++
 docs/sphinx/qapidoc.py                 | 948 ++++++++++++++-----------
 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                 | 121 +++-
 scripts/qapi/source.py                 |   4 +-
 tests/qapi-schema/doc-good.out         |  10 +-
 tests/qapi-schema/test-qapi.py         |   2 +-
 19 files changed, 3069 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 9, 2025, 9:19 p.m. UTC | #1

Would you be willing to serve as maintainer of (a subset of)
docs/sphinx/?  If yes, please make it official by patching MAINTAINERS.