From nobody Sun Apr 6 22:11:16 2025 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass(p=none dis=none) header.from=redhat.com ARC-Seal: i=1; a=rsa-sha256; t=1736881534; cv=none; d=zohomail.com; s=zohoarc; b=MYOOjpnBNb76IZ+BIJP3qnQJviHocC2uhr2bShZ7Ix8ApoZGmBzQTULKm+NEvewAUs0awMXpsvBacXSL5i11VKw8ag/aShmABmXj5qJp/oWhNeZ0TCIk4cjTHTBS35uiFDV3TVZ5x6ZfICxwlHj7Rq+XYyjZF7DUpEKhJ85hdXE= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1736881534; h=Content-Transfer-Encoding:Cc:Cc:Date:Date:From:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:Subject:To:To:Message-Id:Reply-To; bh=Y+YkRE0jmFIrVCtqYhqBKeexad8OLiX2Y5aip/6UJg4=; b=mw4REVhFjRT/SnJNWSMqLtplZaKrMfV03inhvTGuxMQFV4OqB1YoPPFXhCsxCYkC4TmvkL4ypHfpuYTwC8vIOt7SBCTmmWKXyClnNUC+ouOGzsB0als8YogTvdp/tm+sreoQU4NVjf9ZXwuN8r7aTGrqh6vuMxeiyrHdsCU/GHI= ARC-Authentication-Results: i=1; mx.zohomail.com; dkim=pass; spf=pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=qemu-devel-bounces+importer=patchew.org@nongnu.org; dmarc=pass header.from= (p=none dis=none) Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1736881534466173.6014167695854; Tue, 14 Jan 2025 11:05:34 -0800 (PST) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tXm8Z-0005l1-MR; Tue, 14 Jan 2025 13:59:39 -0500 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 1tXm7w-0005fC-4J for qemu-devel@nongnu.org; Tue, 14 Jan 2025 13:59:03 -0500 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 1tXm7u-0002lV-7L for qemu-devel@nongnu.org; Tue, 14 Jan 2025 13:58:59 -0500 Received: from mx-prod-mc-05.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-552-SdbHP4xzMwSldy8HWbKo9g-1; Tue, 14 Jan 2025 13:58:56 -0500 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-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id F236C1956080; Tue, 14 Jan 2025 18:58:54 +0000 (UTC) Received: from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.64.175]) by mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP id E35DF19560A3; Tue, 14 Jan 2025 18:58:53 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1736881137; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=Y+YkRE0jmFIrVCtqYhqBKeexad8OLiX2Y5aip/6UJg4=; b=cvJN91l/EQ7fK2snFALSXjjHgJbcZesPnOUu9uHVS9SaIHWdunsaOIPoC+dQdEqVFEjcC/ te/lJKYQQomzcJPsseckmmxEp86IaAR1Z3yIAveie/bpIggkmOhS6B74v8WWPAi0HbuzEy Va/KhZojw7C7rfDN+giOEU7HtsINa3w= X-MC-Unique: SdbHP4xzMwSldy8HWbKo9g-1 X-Mimecast-MFC-AGG-ID: SdbHP4xzMwSldy8HWbKo9g From: John Snow To: qemu-devel@nongnu.org Cc: Michael Roth , Peter Maydell , Markus Armbruster , John Snow Subject: [PATCH v2 07/23] docs/qapidoc: add transmogrifier class stub Date: Tue, 14 Jan 2025 13:58:24 -0500 Message-ID: <20250114185840.3058525-8-jsnow@redhat.com> In-Reply-To: <20250114185840.3058525-1-jsnow@redhat.com> References: <20250114185840.3058525-1-jsnow@redhat.com> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable X-Scanned-By: MIMEDefang 3.0 on 10.30.177.12 Received-SPF: pass (zohomail.com: domain of gnu.org designates 209.51.188.17 as permitted sender) client-ip=209.51.188.17; envelope-from=qemu-devel-bounces+importer=patchew.org@nongnu.org; helo=lists.gnu.org; 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: -39 X-Spam_score: -4.0 X-Spam_bar: ---- X-Spam_report: (-4.0 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.063, 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=-1.794, 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+importer=patchew.org@nongnu.org Sender: qemu-devel-bounces+importer=patchew.org@nongnu.org X-ZohoMail-DKIM: pass (identity @redhat.com) X-ZM-MESSAGEID: 1736881536020019000 Content-Type: text/plain; charset="utf-8" Add the beginnings of the Transmogrifier class by adding the rST conversion helpers that will be used to build the virtual rST document. This version of the class does not actually "do anything" yet; each individual feature is added one-at-a-time in the forthcoming commits. Signed-off-by: John Snow --- docs/sphinx/qapidoc.py | 66 +++++++++++++++++++++++++++++++++++++++++- 1 file changed, 65 insertions(+), 1 deletion(-) diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py index dc72f3fd3f3..6593c3f28cd 100644 --- a/docs/sphinx/qapidoc.py +++ b/docs/sphinx/qapidoc.py @@ -24,6 +24,7 @@ https://www.sphinx-doc.org/en/master/development/index.html """ =20 +from contextlib import contextmanager import os import re import sys @@ -32,11 +33,12 @@ =20 from docutils import nodes from docutils.parsers.rst import Directive, directives -from docutils.statemachine import ViewList +from docutils.statemachine import StringList, ViewList from qapi.error import QAPIError, QAPISemError from qapi.gen import QAPISchemaVisitor from qapi.parser import QAPIDoc from qapi.schema import QAPISchema +from qapi.source import QAPISourceInfo =20 from sphinx import addnodes from sphinx.directives.code import CodeBlock @@ -61,6 +63,68 @@ def dedent(text: str) -> str: return lines[0] + textwrap.dedent("".join(lines[1:])) =20 =20 +class Transmogrifier: + def __init__(self, schema): + self._result =3D StringList() + self.indent =3D 0 + + # General-purpose rST generation functions + + def get_indent(self) -> str: + return " " * self.indent + + @contextmanager + def indented(self): + self.indent +=3D 1 + try: + yield + finally: + self.indent -=3D 1 + + def add_line_raw(self, line: str, source: str, *lineno: int) -> None: + """Append one line of generated reST to the output.""" + + # NB: Sphinx uses zero-indexed lines; subtract one. + lineno =3D tuple((n - 1 for n in lineno)) + + if line.strip(): + # not a blank line + self._result.append( + self.get_indent() + line.rstrip("\n"), source, *lineno + ) + else: + self._result.append("", source, *lineno) + + def add_line(self, content: str, info: QAPISourceInfo) -> None: + # NB: We *require* an info object; this works out OK because we + # don't document built-in objects that don't have + # one. Everything else should. + assert info + self.add_line_raw(content, info.fname, info.line) + + def add_lines( + self, + content: str, + info: QAPISourceInfo, + ) -> None: + assert info + lines =3D content.splitlines(True) + for i, line in enumerate(lines): + self.add_line_raw(line, info.fname, info.line + i) + + def ensure_blank_line(self) -> None: + # Empty document -- no blank line required. + if not self._result: + return + + # Last line isn't blank, add one. + if self._result[-1].strip(): # pylint: disable=3Dno-member + fname, line =3D self._result.info(-1) + # New blank line is credited to one-after the current last lin= e. + # +2: correct for zero/one index, then increment by one. + self.add_line_raw("", fname, line + 2) + + # Disable black auto-formatter until re-enabled: # fmt: off =20 --=20 2.47.1