From patchwork Wed Jun 26 22:21:06 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: John Snow X-Patchwork-Id: 13713479 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 C956EC41513 for ; Wed, 26 Jun 2024 22:25:26 +0000 (UTC) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1sMb1i-00056O-Bx; Wed, 26 Jun 2024 18:22:06 -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 1sMb1V-00051I-5L for qemu-devel@nongnu.org; Wed, 26 Jun 2024 18:21:54 -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 1sMb1Q-0002BU-Ns for qemu-devel@nongnu.org; Wed, 26 Jun 2024 18:21:52 -0400 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1719440506; 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=3ppBhmEFfudZ224+zKt2e2juuCee+bLNx3yjzAK3WEs=; b=UWAS5IF+e5VNDqbDe87oYMEhQKN5c/t0gke98Lgd+QhngwqUnbg9iYIqocnJGQoTRMAPek pd5uEXeGR1uJ1uHWsiBfIUK+uwrQnvEKb0PHAlFkaSm0N0eRbICiToW6wrzkHyE8Id6v8S O0UG2KnbinaVXMn0u3QFPvNfxM2Ybqc= 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-263-SUskzvo0OdeKRIcoRGLXZg-1; Wed, 26 Jun 2024 18:21:45 -0400 X-MC-Unique: SUskzvo0OdeKRIcoRGLXZg-1 Received: from mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com (mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.12]) (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 0FB7619560B5; Wed, 26 Jun 2024 22:21:41 +0000 (UTC) Received: from scv.redhat.com (unknown [10.22.8.67]) by mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id 50BA819560BF; Wed, 26 Jun 2024 22:21:30 +0000 (UTC) From: John Snow To: qemu-devel@nongnu.org Cc: Mads Ynddal , Jiri Pirko , Stefan Hajnoczi , Eric Blake , Peter Maydell , Michael Roth , "Michael S. Tsirkin" , Alex Williamson , Pavel Dovgalyuk , Victor Toso de Carvalho , =?utf-8?q?C=C3=A9dric_Le_G?= =?utf-8?q?oater?= , =?utf-8?q?Daniel_P=2E_Berrang=C3=A9?= , qemu-block@nongnu.org, Ani Sinha , Fabiano Rosas , Marcel Apfelbaum , =?utf-8?q?Marc-Andr=C3=A9_Lu?= =?utf-8?q?reau?= , Gerd Hoffmann , Paolo Bonzini , Kevin Wolf , Peter Xu , Eduardo Habkost , Markus Armbruster , =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= , Lukas Straub , Igor Mammedov , Jason Wang , Yanan Wang , Hanna Reitz , Konstantin Kostiuk , Stefan Berger , John Snow Subject: [PATCH v2 00/21] qapi: convert "Note" and "Example" sections to rST Date: Wed, 26 Jun 2024 18:21:06 -0400 Message-ID: <20240626222128.406106-1-jsnow@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 3.0 on 10.30.177.12 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: -22 X-Spam_score: -2.3 X-Spam_bar: -- X-Spam_report: (-2.3 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.207, 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, 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 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".) V2: - Lotsa stuff :{ - Added new example box styling and sphinx directive macro - Addressed... most? list feedback. (But not the indent split.) Known issues: - The Example boxes are styled a little wonkily if prose follows the code-block instead of precedes it, fixup will be tomorrow. --js Harmonie Snow (1): docs/sphinx: add CSS styling for qmp-example directive John Snow (20): [DO-NOT-MERGE]: Add some ad-hoc linting helpers. qapi: linter fixups docs/qapidoc: remove unused intersperse function 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: nail down convention that Errors sections are lists 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 docs/qapidoc: factor out do_parse() docs/qapidoc: create qmp-example directive docs/qapidoc: add QMP highlighting to annotated qmp-example blocks qapi: convert "Example" sections without titles qapi: convert "Example" sections with titles qapi: convert "Example" sections with longer prose qapi: remove "Example" doc section docs/devel/qapi-code-gen.rst | 25 +- docs/sphinx-static/theme_overrides.css | 46 ++++ docs/sphinx/qapidoc.py | 258 +++++++++++++----- qapi/acpi.json | 4 +- qapi/block-core.json | 116 ++++---- qapi/block.json | 59 ++-- qapi/char.json | 36 ++- qapi/control.json | 28 +- qapi/dump.json | 10 +- qapi/introspect.json | 6 +- qapi/machine-target.json | 28 +- qapi/machine.json | 117 ++++---- qapi/migration.json | 104 +++---- qapi/misc-target.json | 22 +- qapi/misc.json | 123 +++++---- qapi/net.json | 32 ++- qapi/pci.json | 10 +- qapi/qdev.json | 40 +-- qapi/qom.json | 33 ++- qapi/replay.json | 8 +- qapi/rocker.json | 26 +- qapi/run-state.json | 48 ++-- qapi/sockets.json | 10 +- qapi/stats.json | 22 +- qapi/tpm.json | 6 +- qapi/trace.json | 4 +- qapi/transaction.json | 12 +- qapi/ui.json | 76 +++--- qapi/vfio.json | 2 +- qapi/virtio.json | 57 ++-- qapi/yank.json | 4 +- qga/qapi-schema.json | 48 ++-- scripts/qapi-lint.sh | 61 +++++ scripts/qapi/Makefile | 5 + scripts/qapi/introspect.py | 8 +- scripts/qapi/parser.py | 38 ++- 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 | 28 +- tests/qapi-schema/doc-good.out | 61 +++-- tests/qapi-schema/doc-good.txt | 36 ++- .../qapi-schema/doc-interleaved-section.json | 2 +- 44 files changed, 1010 insertions(+), 664 deletions(-) create mode 100755 scripts/qapi-lint.sh create mode 100644 scripts/qapi/Makefile