From nobody Mon Feb 9 18:45:58 2026 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=1606901013; cv=none; d=zohomail.com; s=zohoarc; b=igpQba5Y+bRl3tKhyhAkwWIIDfBU5qBfsk9mvexP6D9y10HyI27w/HyvQQdbKvfcRt+iTzqpj9MyDrHzLhnq/1OQCeUQyccnO9sPWc4jY2n5Y3/2mxFWMsLOwMLmIlfM2OOkUGaoDviafTLfOTNWbMM1YX7TAcHoGLU9n7xb7P4= ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=zohomail.com; s=zohoarc; t=1606901013; h=Content-Type:Content-Transfer-Encoding:Date:From:In-Reply-To:List-Subscribe:List-Post:List-Id:List-Archive:List-Help:List-Unsubscribe:MIME-Version:Message-ID:References:Sender:Subject:To; bh=e8hnoZGivgr313ZDbOqA0Nv2kwefhhsEAfF44TGY+aU=; b=P/3CLxeBaoft7xf0ab/Qz9h7ZnfrADXw/vFTmfVSdRqTWlkjU9nIqDf3u8HVe4B6XziKAsR3yswN08nwDFID/+rXFbVO5bgfUJOQwKYtvvQ5eda+b5HvUWOujf4FwDpBQlEZ54szzvV3LCwKJXUSCAeziaDVzTFuEL+dywD8z8w= 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) header.from= Return-Path: Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) by mx.zohomail.com with SMTPS id 1606901013084632.8874650401935; Wed, 2 Dec 2020 01:23:33 -0800 (PST) Received: from localhost ([::1]:55362 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1kkOMF-0002U0-Vw for importer@patchew.org; Wed, 02 Dec 2020 04:23:32 -0500 Received: from eggs.gnu.org ([2001:470:142:3::10]:40918) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1kkNDO-0003xI-Gl for qemu-devel@nongnu.org; Wed, 02 Dec 2020 03:10:18 -0500 Received: from us-smtp-delivery-124.mimecast.com ([63.128.21.124]:53870) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_CBC_SHA1:256) (Exim 4.90_1) (envelope-from ) id 1kkNCe-0003rL-0I for qemu-devel@nongnu.org; Wed, 02 Dec 2020 03:10:18 -0500 Received: from mimecast-mx01.redhat.com (mimecast-mx01.redhat.com [209.132.183.4]) (Using TLS) by relay.mimecast.com with ESMTP id us-mta-486-MSzugtTQNCuUtLdG7UStcg-1; Wed, 02 Dec 2020 03:09:27 -0500 Received: from smtp.corp.redhat.com (int-mx06.intmail.prod.int.phx2.redhat.com [10.5.11.16]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mimecast-mx01.redhat.com (Postfix) with ESMTPS id E3BA7185E489 for ; Wed, 2 Dec 2020 08:09:26 +0000 (UTC) Received: from virtlab701.virt.lab.eng.bos.redhat.com (virtlab701.virt.lab.eng.bos.redhat.com [10.19.152.228]) by smtp.corp.redhat.com (Postfix) with ESMTP id A80CE5C1B4 for ; Wed, 2 Dec 2020 08:09:26 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1606896571; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=e8hnoZGivgr313ZDbOqA0Nv2kwefhhsEAfF44TGY+aU=; b=LtEUVkvguKY8Q/BpU4I1RD2kMJ0pnPAUsBeV0xG1xwsirKr65G6i1Mo2F9VTTplq1CGlge iPP8nIL8UtpIV1YzrYfcnooXXdK5XB8+LsogIU/hzAVlroOVcffBIfx+SlSAFUXoH4Ccnl 75wjoNPAbYAXaBWfwMLwdhK8yG4LTq0= X-MC-Unique: MSzugtTQNCuUtLdG7UStcg-1 From: Paolo Bonzini To: qemu-devel@nongnu.org Subject: [PULL 099/113] scripts: kernel-doc: use a less pedantic markup for funcs on Sphinx 3.x Date: Wed, 2 Dec 2020 03:08:35 -0500 Message-Id: <20201202080849.4125477-100-pbonzini@redhat.com> In-Reply-To: <20201202080849.4125477-1-pbonzini@redhat.com> References: <20201202080849.4125477-1-pbonzini@redhat.com> MIME-Version: 1.0 X-Scanned-By: MIMEDefang 2.79 on 10.5.11.16 Authentication-Results: relay.mimecast.com; auth=pass smtp.auth=CUSA124A263 smtp.mailfrom=pbonzini@redhat.com X-Mimecast-Spam-Score: 0 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: quoted-printable 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=63.128.21.124; envelope-from=pbonzini@redhat.com; helo=us-smtp-delivery-124.mimecast.com X-Spam_score_int: -35 X-Spam_score: -3.6 X-Spam_bar: --- X-Spam_report: (-3.6 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-1.497, 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.23 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" X-ZohoMail-DKIM: pass (identity @redhat.com) Content-Type: text/plain; charset="utf-8" From: Mauro Carvalho Chehab Unfortunately, Sphinx 3.x parser for c functions is too pedantic: https://github.com/sphinx-doc/sphinx/issues/8241 While it could be relaxed with some configurations, there are several corner cases that it would make it hard to maintain, and will require teaching conf.py about several macros. So, let's instead use the :c:macro notation. This will produce an output that it is not as nice as currently, but it should still be acceptable, and will provide cross-references, removing thousands of warnings when building with newer versions of Sphinx. Signed-off-by: Mauro Carvalho Chehab Signed-off-by: Paolo Bonzini Message-Id: <20201117165312.118257-18-pbonzini@redhat.com> Signed-off-by: Paolo Bonzini --- scripts/kernel-doc | 34 ++++++++++++++++++++++++---------- 1 file changed, 24 insertions(+), 10 deletions(-) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 771367a6ab..75ddd3b5e6 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -886,19 +886,29 @@ sub output_function_rst(%) { my $oldprefix =3D $lineprefix; my $start =3D ""; =20 - if ($args{'typedef'}) { - if ($sphinx_major < 3) { + if ($sphinx_major < 3) { + if ($args{'typedef'}) { print ".. c:type:: ". $args{'function'} . "\n\n"; + print_lineno($declaration_start_line); + print " **Typedef**: "; + $lineprefix =3D ""; + output_highlight_rst($args{'purpose'}); + $start =3D "\n\n**Syntax**\n\n ``"; } else { - print ".. c:function:: ". $args{'function'} . "\n\n"; + print ".. c:function:: "; } - print_lineno($declaration_start_line); - print " **Typedef**: "; - $lineprefix =3D ""; - output_highlight_rst($args{'purpose'}); - $start =3D "\n\n**Syntax**\n\n ``"; } else { - print ".. c:function:: "; + print ".. c:macro:: ". $args{'function'} . "\n\n"; + + if ($args{'typedef'}) { + print_lineno($declaration_start_line); + print " **Typedef**: "; + $lineprefix =3D ""; + output_highlight_rst($args{'purpose'}); + $start =3D "\n\n**Syntax**\n\n ``"; + } else { + print "``"; + } } if ($args{'functiontype'} ne "") { $start .=3D $args{'functiontype'} . " " . $args{'function'} . " ("; @@ -925,7 +935,11 @@ sub output_function_rst(%) { if ($args{'typedef'}) { print ");``\n\n"; } else { - print ")\n\n"; + if ($sphinx_major < 3) { + print ")\n\n"; + } else { + print ")``\n"; + } print_lineno($declaration_start_line); $lineprefix =3D " "; output_highlight_rst($args{'purpose'}); --=20 2.26.2