[PATCH 00/57] docs: Add new QAPI transmogrifier

[John Snow <jsnow@redhat.com>]

Hi! This series is based on armbru/pull-qapi-2025-02-26.

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-29 implement the qapi_domain extension.
Patches 30-57 implement the qapidoc "Transmogrifier".

This series is still "RFC" quality, though it's quite nearly actually
ready for inclusion. The "add transmogrifier test document" patch is not
intended for actual merge, it's just there to demonstrate the new
document generator by producing output in docs/manual/qapi/index.html.

Known shortcomings in this series:

- Still no new QAPI unit tests. I'll add those for next go-around.
- No new documentation. Also for next revision. I'll document the QAPI
  domain syntax and give a brief overview of how the transmogrifier
  functions, and a quick rundown of any new rST syntax that may be
  pertinent to QAPI documentation writers.
- IFCOND information is still rendered in two places, we'll need to
  decide where and how we want to render it.
- No QAPI namespace support ... yet. So we can't enable it for QMP, QGA
  and QSD simultaneously just yet. I don't think it will be difficult.

Unknown shortcomings in this series:

- ???

New stuff overall from the last iteration of this series:

- @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.

I really must stress again how frustratingly difficult it was to achieve
the prior two bullet points. I *do* in fact want a cookie and/or an
award ribbon.

--js

John Snow (57):
  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:module directive
  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 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 "Returns:" 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: disambiguate cross-references
  docs/qapidoc: add transmogrifier test document
  docs/qapidoc: process @foo into ``foo``
  docs/qapidoc: add intermediate output debugger
  docs/qapidoc: Add "the members of" pointers

 docs/conf.py                           |  18 +-
 docs/devel/codebase.rst                |   6 +-
 docs/glossary.rst                      |  10 +-
 docs/index.rst                         |   1 +
 docs/qapi/index.rst                    |  53 ++
 docs/sphinx-static/theme_overrides.css |  98 ++-
 docs/sphinx/compat.py                  | 229 ++++++
 docs/sphinx/qapi_domain.py             | 981 +++++++++++++++++++++++++
 docs/sphinx/qapidoc.py                 | 948 +++++++++++++-----------
 docs/sphinx/qapidoc_legacy.py          | 440 +++++++++++
 scripts/qapi-lint.sh                   |  55 ++
 scripts/qapi/backend.py                |   2 +
 scripts/qapi/main.py                   |  10 +-
 scripts/qapi/parser.py                 | 118 ++-
 scripts/qapi/source.py                 |   4 +-
 tests/qapi-schema/doc-good.out         |  10 +-
 tests/qapi-schema/test-qapi.py         |   2 +-
 17 files changed, 2498 insertions(+), 487 deletions(-)
 create mode 100644 docs/qapi/index.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

-- 
2.48.1