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
