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