From patchwork Sun Mar 9 08:34:47 2025 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: John Snow X-Patchwork-Id: 14008149 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 D20B7C282D1 for ; Sun, 9 Mar 2025 08:36:09 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1trC8e-0000iR-BU; Sun, 09 Mar 2025 04:36:00 -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 1trC8c-0000dw-Od for qemu-devel@nongnu.org; Sun, 09 Mar 2025 04:35:58 -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 1trC8b-0001zh-05 for qemu-devel@nongnu.org; Sun, 09 Mar 2025 04:35:58 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741509356; 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=JxiusdFM4yuXUh+fVwTw71zchLQQeAz9jeF4iUcPmIc=; b=gs/uhjGMpTQrqNlctWe96Iar03s+FRTHBkSA9/qxXdON6ruuedLDtbhAk6lB63tY5p5pKQ 5vDiBH6J8mq4BXIZ4g8H4AtekJV6OjWsYJW4w3tFvjrdpLIAzCml4hGAiMM2Ft7Bka1ng5 0PBoXCxYnUxq3hGdYMrwWiVHb+sOQdY= 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-522-bGGZcq1dOl-4BKrDsjrMbA-1; Sun, 09 Mar 2025 04:35:54 -0400 X-MC-Unique: bGGZcq1dOl-4BKrDsjrMbA-1 X-Mimecast-MFC-AGG-ID: bGGZcq1dOl-4BKrDsjrMbA_1741509353 Received: from mx-prod-int-04.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-04.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.40]) (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 68A2D180035E; Sun, 9 Mar 2025 08:35:53 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.64.4]) by mx-prod-int-04.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 4736419560AB; Sun, 9 Mar 2025 08:35:51 +0000 (UTC) From: John Snow To: qemu-devel@nongnu.org Cc: Markus Armbruster , =?utf-8?q?Philippe_Mathieu-Daud?= =?utf-8?q?=C3=A9?= , Michael Roth , =?utf-8?q?Daniel_P=2E_Berrang=C3=A9?= , Eric Blake , Thomas Huth , =?utf-8?q?A?= =?utf-8?q?lex_Benn=C3=A9e?= , Peter Maydell , John Snow Subject: [PATCH v2 00/62] docs: Add new QAPI transmogrifier Date: Sun, 9 Mar 2025 04:34:47 -0400 Message-ID: <20250309083550.5155-1-jsnow@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.0 on 10.30.177.40 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 nice features for later. Patches 3-31 implement the qapi_domain extension. Patches 32-59 implement the qapidoc "Transmogrifier". Known shortcomings in this series: - Some ifcond information 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. - Didn't finish addressing all of Markus' feedback, but needed to get another spin out on the list ASAP. 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 (62): 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 ObjectDescription 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: 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/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 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 | 926 ++++++++++++++++++++++++ docs/sphinx/qapidoc.py | 948 ++++++++++++++----------- 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 | 121 +++- scripts/qapi/source.py | 4 +- tests/qapi-schema/doc-good.out | 10 +- tests/qapi-schema/test-qapi.py | 2 +- 19 files changed, 3069 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