From patchwork Wed Jun 19 00:29:59 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: John Snow X-Patchwork-Id: 1949535 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@legolas.ozlabs.org Authentication-Results: legolas.ozlabs.org; dkim=pass (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=R54IGBz2; dkim-atps=neutral Authentication-Results: legolas.ozlabs.org; spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org (client-ip=209.51.188.17; helo=lists.gnu.org; envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org; receiver=patchwork.ozlabs.org) Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-ECDSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by legolas.ozlabs.org (Postfix) with ESMTPS id 4W3l1964p1z20ZM for ; Wed, 19 Jun 2024 10:31:41 +1000 (AEST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1sJjDq-0005qC-RJ; Tue, 18 Jun 2024 20:30:46 -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 1sJjDq-0005p9-1T for qemu-devel@nongnu.org; Tue, 18 Jun 2024 20:30:46 -0400 Received: from us-smtp-delivery-124.mimecast.com ([170.10.129.124]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1sJjDo-0001Gt-2V for qemu-devel@nongnu.org; Tue, 18 Jun 2024 20:30:45 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1718757042; 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=4gl0+5pfkZW2ghJc+QLiSsyQdXIc10W0zM/jWJDDcKY=; b=R54IGBz2YNiLM/hR/bT2+zpRrCKh8XwrgBT0+1zyAba5gPbJzowcJVT1qsdTX6N6G9asdA hJ3DHpvN5dZtAYVGx5qt6/gb+NkaeCt2flfzcIpKW0stRHGoDJIP2p9JYOO+UUludPmPOJ MmwzYqjLxHooY6AoAiD+YhyUwVmBoHo= Received: from mx-prod-mc-03.mail-002.prod.us-west-2.aws.redhat.com (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-325-yeHTznzPNsC90jjuxjNpeQ-1; Tue, 18 Jun 2024 20:30:34 -0400 X-MC-Unique: yeHTznzPNsC90jjuxjNpeQ-1 Received: from mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.15]) (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-03.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 47E5A1956051; Wed, 19 Jun 2024 00:30:31 +0000 (UTC) Received: from scv.localdomain (unknown [10.22.16.38]) by mx-prod-int-02.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id EFE2D1955E80; Wed, 19 Jun 2024 00:30:13 +0000 (UTC) From: John Snow To: qemu-devel@nongnu.org Cc: Stefan Hajnoczi , Hanna Reitz , Michael Roth , =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Victor Toso de Carvalho , "Michael S. Tsirkin" , Konstantin Kostiuk , Yanan Wang , Pavel Dovgalyuk , =?utf-8?q?Marc-Andr=C3=A9_Lurea?= =?utf-8?q?u?= , Marcel Apfelbaum , Fabiano Rosas , Lukas Straub , Eduardo Habkost , Mads Ynddal , =?utf-8?q?Daniel_P=2E_Berrang=C3=A9?= , Gerd Hoffmann , Stefan Berger , Peter Xu , Igor Mammedov , =?utf-8?q?C=C3=A9dric_Le_Goater?= , Jason Wang , Ani Sinha , Markus Armbruster , Paolo Bonzini , Peter Maydell , qemu-block@nongnu.org, Jiri Pirko , Alex Williamson , Kevin Wolf , Eric Blake , John Snow Subject: [PATCH 00/13] qapi: convert "Note" and "Example" sections to rST Date: Tue, 18 Jun 2024 20:29:59 -0400 Message-ID: <20240619003012.1753577-1-jsnow@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.0 on 10.30.177.15 Received-SPF: pass client-ip=170.10.129.124; envelope-from=jsnow@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: 11 X-Spam_score: 1.1 X-Spam_bar: + X-Spam_report: (1.1 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.148, 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_H4=0.001, RCVD_IN_MSPIKE_WL=0.001, RCVD_IN_SBL_CSS=3.335, SPF_HELO_NONE=0.001, SPF_PASS=-0.001, T_SCC_BODY_TEXT_LINE=-0.01 autolearn=no 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+incoming=patchwork.ozlabs.org@nongnu.org Sender: qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org This series focuses primarily on converting our existing QAPI/QMP documentation to remove special "Note" and "Example" sections in favor of rST markup for the same. This is being done primarily to reduce the number of specially parsed QAPI sections we have in favor of allowing fully arbitrary rST markup for greater flexibility and freedom in styling the rendered HTML documentation. (A tangible side benefit is that the new qapidoc generator has fewer sections to reason about when it splices inherited documentation together for the QMP reference manual; docs largely preserve the order of documentation "as written" instead of needing to splice multiple separate sections together. A goal of the new generator is to eventually remove all tagged sections except for "members" and "features".) Known issues: - The caption syntax for QMP examples is a little ugly in rendered HTML output; My CSS intern wasn't available before publication time to fix it ;) -- Will fix with an amendment patch at next opportunity. Any feedback not implemented should be interpreted as evidence of a forgetful (rather than a spiteful) mind. Please remind me where appropriate. --js John Snow (13): [DO-NOT-MERGE]: Add some ad-hoc linting helpers. qapi: linter fixups docs/qapidoc: delint a tiny portion of the module qapi/parser: preserve indentation in QAPIDoc sections qapi/parser: fix comment parsing immediately following a doc block docs/qapidoc: fix nested parsing under untagged sections qapi: fix non-compliant JSON examples qapi: ensure all errors sections are uniformly typset qapi: convert "Note" sections to plain rST qapi: update prose in note blocks qapi: add markup to note blocks qapi/parser: don't parse rST markup as section headers qapi: convert "Example" sections to rST docs/devel/qapi-code-gen.rst | 25 +-- docs/sphinx/qapidoc.py | 103 ++++++++---- qapi/acpi.json | 6 +- qapi/block-core.json | 148 +++++++++------- qapi/block.json | 62 ++++--- qapi/char.json | 48 ++++-- qapi/control.json | 32 ++-- qapi/dump.json | 14 +- qapi/introspect.json | 6 +- qapi/machine-target.json | 29 ++-- qapi/machine.json | 125 ++++++++------ qapi/migration.json | 159 ++++++++++++------ qapi/misc-target.json | 33 ++-- qapi/misc.json | 139 ++++++++------- qapi/net.json | 42 +++-- qapi/pci.json | 11 +- qapi/qapi-schema.json | 6 +- qapi/qdev.json | 45 ++--- qapi/qom.json | 39 +++-- qapi/replay.json | 12 +- qapi/rocker.json | 30 ++-- qapi/run-state.json | 63 ++++--- qapi/sockets.json | 10 +- qapi/stats.json | 22 +-- qapi/tpm.json | 9 +- qapi/trace.json | 6 +- qapi/transaction.json | 13 +- qapi/ui.json | 93 +++++----- qapi/vfio.json | 3 +- qapi/virtio.json | 50 +++--- qapi/yank.json | 6 +- qga/qapi-schema.json | 48 +++--- scripts/qapi-lint.sh | 59 +++++++ scripts/qapi/Makefile | 5 + scripts/qapi/introspect.py | 8 +- scripts/qapi/parser.py | 40 ++++- scripts/qapi/schema.py | 6 +- scripts/qapi/visit.py | 5 +- tests/qapi-schema/doc-empty-section.err | 2 +- tests/qapi-schema/doc-empty-section.json | 2 +- tests/qapi-schema/doc-good.json | 21 ++- tests/qapi-schema/doc-good.out | 62 ++++--- tests/qapi-schema/doc-good.txt | 31 ++-- .../qapi-schema/doc-interleaved-section.json | 2 +- 44 files changed, 1036 insertions(+), 644 deletions(-) create mode 100755 scripts/qapi-lint.sh create mode 100644 scripts/qapi/Makefile Reviewed-by: Michael S. Tsirkin