From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-18.6 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,INCLUDES_PATCH,MAILING_LIST_MULTI, MENTIONS_GIT_HOSTING,SIGNED_OFF_BY,SPF_HELO_NONE,SPF_PASS,URIBL_BLOCKED, USER_AGENT_GIT autolearn=unavailable autolearn_force=no version=3.4.0 Received: from mail.kernel.org (mail.kernel.org [198.145.29.99]) by smtp.lore.kernel.org (Postfix) with ESMTP id 59A16C4727E for ; Wed, 30 Sep 2020 13:28:28 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 1B17220754 for ; Wed, 30 Sep 2020 13:28:27 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1601472508; bh=dvscQSQ3r76uf25CRGEczXRFWyqPHOnByQGLKLyfwNw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=IYT7y1VNLtRu7E/w19XAUVXZF8+VdFj+DSxXcuzEx0cFgUO+UcLxKrjG/IsllXcUl zxkumCU6Ua+Tl/oOPp8aFHsJYYaLAsrdV7Wb+4GhnwIafm+QnsehbZycIpZq7kWAJ1 wab9tI60fErhMDsIjfnAAMsQ0ttHLj/gC8/CX5fw= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1730819AbgI3N20 (ORCPT ); Wed, 30 Sep 2020 09:28:26 -0400 Received: from mail.kernel.org ([198.145.29.99]:38786 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1730173AbgI3NZU (ORCPT ); Wed, 30 Sep 2020 09:25:20 -0400 Received: from mail.kernel.org (ip5f5ad5c4.dynamic.kabel-deutschland.de [95.90.213.196]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by mail.kernel.org (Postfix) with ESMTPSA id DF21520BED; Wed, 30 Sep 2020 13:25:19 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1601472320; bh=dvscQSQ3r76uf25CRGEczXRFWyqPHOnByQGLKLyfwNw=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=ri5iEeYHdlLH6ctBLppZjoXcudnE3yGnfa/Z/p3XUmmkhN8zsPhku1y4nvp+gYN+4 0ezxfKrWbuhTdB7DT4LniGUx/7TqLr7LVDP5fetV7AyscLocyupQln+mkTjpxGwA5F 0YyG8jCwmOARWJH+dQn0ZSt5SPTnfH8Y3IJB6Fhc= Received: from mchehab by mail.kernel.org with local (Exim 4.94) (envelope-from ) id 1kNc6f-001XJ0-NM; Wed, 30 Sep 2020 15:25:17 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List , Jonathan Corbet Cc: Mauro Carvalho Chehab , linux-kernel@vger.kernel.org Subject: [PATCH v4 05/52] scripts: kernel-doc: use a less pedantic markup for funcs on Sphinx 3.x Date: Wed, 30 Sep 2020 15:24:28 +0200 Message-Id: <65003bc1c62d1e6108961fba18e3e734e23d5c86.1601467849.git.mchehab+huawei@kernel.org> X-Mailer: git-send-email 2.26.2 In-Reply-To: References: MIME-Version: 1.0 Content-Transfer-Encoding: 8bit Sender: Mauro Carvalho Chehab Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org 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 --- scripts/kernel-doc | 34 ++++++++++++++++++++++++---------- 1 file changed, 24 insertions(+), 10 deletions(-) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 3efc06d6f82d..e1140869b889 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -886,19 +886,29 @@ sub output_function_rst(%) { my $oldprefix = $lineprefix; my $start = ""; - 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 = ""; + output_highlight_rst($args{'purpose'}); + $start = "\n\n**Syntax**\n\n ``"; } else { - print ".. c:function:: ". $args{'function'} . "\n\n"; + print ".. c:function:: "; } - print_lineno($declaration_start_line); - print " **Typedef**: "; - $lineprefix = ""; - output_highlight_rst($args{'purpose'}); - $start = "\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 = ""; + output_highlight_rst($args{'purpose'}); + $start = "\n\n**Syntax**\n\n ``"; + } else { + print "``"; + } } if ($args{'functiontype'} ne "") { $start .= $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 = " "; output_highlight_rst($args{'purpose'}); -- 2.26.2