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 -- 2.48.1
