From patchwork Tue Mar 11 03:41:58 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: John Snow X-Patchwork-Id: 14010997 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by smtp.lore.kernel.org (Postfix) with ESMTPS id E1405C28B2E for ; Tue, 11 Mar 2025 03:44:56 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1trqWY-0003ip-03; Mon, 10 Mar 2025 23:43:22 -0400 Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1trqWW-0003i6-Cz for qemu-devel@nongnu.org; Mon, 10 Mar 2025 23:43:20 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.133.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1trqWU-00028f-K4 for qemu-devel@nongnu.org; Mon, 10 Mar 2025 23:43:20 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741664596; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=HdyODpO2mpbvhSYjnvMw9H1d0FnwmNXgX+JvBKWG6bI=; b=DfPW7/jZ6TkfrLr8RKOxYXaqLutlOs0OXjwmV+Ni/vaT4D/obAlrmBQSW2o9XKA7WhJEnp THSQ01He5GcKBrhnrS78vocoe3lwus7YNZEl45zbkB985JGYjJYev7SduhuUCROXWRgdd6 XAj574N+lA61zhCCLsN3eRdwcMuQseY= Received: from mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-524-X9gUCSR8P9K7fR2Yj0Lu1g-1; Mon, 10 Mar 2025 23:43:12 -0400 X-MC-Unique: X9gUCSR8P9K7fR2Yj0Lu1g-1 X-Mimecast-MFC-AGG-ID: X9gUCSR8P9K7fR2Yj0Lu1g_1741664591 Received: from mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.93]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest SHA256) (No client certificate requested) by mx-prod-mc-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 03E31180049D; Tue, 11 Mar 2025 03:43:11 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.64.49]) by mx-prod-int-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 60AF41800366; Tue, 11 Mar 2025 03:43:07 +0000 (UTC) From: John Snow To: qemu-devel@nongnu.org Cc: Peter Maydell , John Snow , =?utf-8?q?Daniel_P=2E_Berrang=C3=A9?= , Eric Blake , Michael Roth , Thomas Huth , =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , =?utf-8?q?Alex?= =?utf-8?q?_Benn=C3=A9e?= , Markus Armbruster Subject: [PATCH v3 00/63] docs: Add new QAPI transmogrifier Date: Mon, 10 Mar 2025 23:41:58 -0400 Message-ID: <20250311034303.75779-1-jsnow@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.4.1 on 10.30.177.93 Received-SPF: pass client-ip=170.10.133.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -20 X-Spam_score: -2.1 X-Spam_bar: -- X-Spam_report: (-2.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.001, DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1, RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H2=0.001, RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=0.001, SPF_HELO_NONE=0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no X-Spam_action: no action X-BeenThere: qemu-devel@nongnu.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org Sender: qemu-devel-bounces+qemu-devel=archiver.kernel.org@nongnu.org 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 Acked-by: Markus Armbruster Acked-by: Markus Armbruster