From nobody Fri Apr 4 03:46:02 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=1741692875; cv=none; d=zohomail.com; s=zohoarc; b=HW6TanXvUeDPreMnpYb+RplYOHfVhhdlwTfdOrYBdi8lI/haA9bVZYUCMW+RhnUNq6PcznpvyMlLYQmq9W/jDhhxfFwJUpRVTjseDyKtTQ05fxeOtXKp4KEFQvbghq+6kfBK+lobfJYb59EEtdfvSMsY8rC9vp5gbuBgWtsD3mM= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1741692875; 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=4fzVBga88f/OqmMbr+swR0bwGim42s2bhCCOndnrpmU=; b=F0pHdUiAvFbylBLj2HbHwd1bgtNdNWz+x/8v7TsE/XHdfry/VhYqSCZYYl9LNTiP9sJ0s4+eD0aH22Q0L+t2Slu1EqZVnEaB2QRh+4vUdnDwxLN9PqdzWay+81L8jf5w7IeoVs7R/aYjkE2gpeNolCFA0Oh3fO0wjQkkAFUUw7c= 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 1741692875589704.4164598847585; Tue, 11 Mar 2025 04:34:35 -0700 (PDT) Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1trxrU-000488-IJ; Tue, 11 Mar 2025 07:33:29 -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 1trxpx-00030D-EW for qemu-devel@nongnu.org; Tue, 11 Mar 2025 07:31: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 1trxpt-0006QM-68 for qemu-devel@nongnu.org; Tue, 11 Mar 2025 07:31:51 -0400 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-590-tepSRSfENPSU0Qeosx15QA-1; Tue, 11 Mar 2025 07:31:45 -0400 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-06.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id F3425180034D for ; Tue, 11 Mar 2025 11:31:43 +0000 (UTC) Received: from blackfin.pond.sub.org (unknown [10.22.74.4]) by mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS id 7788F1944F12 for ; Tue, 11 Mar 2025 11:31:42 +0000 (UTC) Received: by blackfin.pond.sub.org (Postfix, from userid 1000) id C19A221E66A4; Tue, 11 Mar 2025 12:31:37 +0100 (CET) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1741692706; 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=4fzVBga88f/OqmMbr+swR0bwGim42s2bhCCOndnrpmU=; b=HPOXADD0Db3dxIIXuVhkyDEuB+8myg4DyUZu3YY6KrEQEoJI7VwLHopxmjU77qWItA5suZ yGa1Lu1Tkl7MQEPAzCn3R4OlCYk4rTQkFnfdypXkfpGu2SeePh1QvlPLvdta2dEoTwMP6k Z+/siBISQahwMSpAQgtFLWJpXVtMNbw= X-MC-Unique: tepSRSfENPSU0Qeosx15QA-1 X-Mimecast-MFC-AGG-ID: tepSRSfENPSU0Qeosx15QA_1741692704 From: Markus Armbruster To: qemu-devel@nongnu.org Cc: stefanha@redhat.com, John Snow Subject: [PULL 04/61] docs/qapi-domain: add QAPI index Date: Tue, 11 Mar 2025 12:30:40 +0100 Message-ID: <20250311113137.1277125-5-armbru@redhat.com> In-Reply-To: <20250311113137.1277125-1-armbru@redhat.com> References: <20250311113137.1277125-1-armbru@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=armbru@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_CERTIFIED_BLOCKED=0.001, RCVD_IN_VALIDITY_RPBL_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: 1741692877568019000 Content-Type: text/plain; charset="utf-8" From: John Snow Use the QAPI object registry to generate a special index just for QAPI definitions. The index can show entries both by definition type and all together, alphabetically. The index can be linked from anywhere in the QEMU manual by using the reference `qapi-index`. Signed-off-by: John Snow Message-ID: <20250311034303.75779-7-jsnow@redhat.com> Acked-by: Markus Armbruster Signed-off-by: Markus Armbruster --- docs/sphinx/qapi_domain.py | 73 ++++++++++++++++++++++++++++++++++++-- 1 file changed, 70 insertions(+), 3 deletions(-) diff --git a/docs/sphinx/qapi_domain.py b/docs/sphinx/qapi_domain.py index f3ece42bc2..3e7718d32d 100644 --- a/docs/sphinx/qapi_domain.py +++ b/docs/sphinx/qapi_domain.py @@ -9,12 +9,20 @@ AbstractSet, Any, Dict, + Iterable, + List, NamedTuple, + Optional, Tuple, ) =20 -from sphinx.domains import Domain, ObjType -from sphinx.locale import __ +from sphinx.domains import ( + Domain, + Index, + IndexEntry, + ObjType, +) +from sphinx.locale import _, __ from sphinx.util import logging =20 =20 @@ -31,6 +39,62 @@ class ObjectEntry(NamedTuple): aliased: bool =20 =20 +class QAPIIndex(Index): + """ + Index subclass to provide the QAPI definition index. + """ + + # pylint: disable=3Dtoo-few-public-methods + + name =3D "index" + localname =3D _("QAPI Index") + shortname =3D _("QAPI Index") + + def generate( + self, + docnames: Optional[Iterable[str]] =3D None, + ) -> Tuple[List[Tuple[str, List[IndexEntry]]], bool]: + assert isinstance(self.domain, QAPIDomain) + content: Dict[str, List[IndexEntry]] =3D {} + collapse =3D False + + # list of all object (name, ObjectEntry) pairs, sorted by name + # (ignoring the module) + objects =3D sorted( + self.domain.objects.items(), + key=3Dlambda x: x[0].split(".")[-1].lower(), + ) + + for objname, obj in objects: + if docnames and obj.docname not in docnames: + continue + + # Strip the module name out: + objname =3D objname.split(".")[-1] + + # Add an alphabetical entry: + entries =3D content.setdefault(objname[0].upper(), []) + entries.append( + IndexEntry( + objname, 0, obj.docname, obj.node_id, obj.objtype, "",= "" + ) + ) + + # Add a categorical entry: + category =3D obj.objtype.title() + "s" + entries =3D content.setdefault(category, []) + entries.append( + IndexEntry(objname, 0, obj.docname, obj.node_id, "", "", "= ") + ) + + # alphabetically sort categories; type names first, ABC entries la= st. + sorted_content =3D sorted( + content.items(), + key=3Dlambda x: (len(x[0]) =3D=3D 1, x[0]), + ) + return sorted_content, collapse + + class QAPIDomain(Domain): """QAPI language domain.""" =20 @@ -54,7 +118,10 @@ class QAPIDomain(Domain): "objects": {}, # fullname -> ObjectEntry } =20 - indices =3D [] + # Index pages to generate; each entry is an Index class. + indices =3D [ + QAPIIndex, + ] =20 @property def objects(self) -> Dict[str, ObjectEntry]: --=20 2.48.1