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=-13.6 required=3.0 tests=BAYES_00,DKIMWL_WL_HIGH, DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,INCLUDES_PATCH,MAILING_LIST_MULTI, SIGNED_OFF_BY,SPF_HELO_NONE,SPF_PASS,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 C80A4C47420 for ; Wed, 30 Sep 2020 13:28:50 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 8BB742075F for ; Wed, 30 Sep 2020 13:28:50 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1601472530; bh=SmKpqxtHJpCpAzM82GJlHhG2suR0vH59MnsXZ7Vi4hQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=f/0Wm8BmhcWxw9+JcnXBdn8H2d7s5FKk5B9+2zobRzqdihaU7C+dtkE12HocT6pXQ tRgkQWbwhkg0WAKp6cK18jzw8X1UVW8mDelnjnVFSphIBVRMw/K234JeWyPy57ZqXm nX4t5UbEEoJqcnX/njzqygL4GweIABg08fF/9eaE= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1730321AbgI3N2p (ORCPT ); Wed, 30 Sep 2020 09:28:45 -0400 Received: from mail.kernel.org ([198.145.29.99]:38766 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1730168AbgI3NZU (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 D56AB20936; 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=SmKpqxtHJpCpAzM82GJlHhG2suR0vH59MnsXZ7Vi4hQ=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=MfjPPlpgZ3orWDkVcC9+k+L/pZIQA1PgLD27IqstqZP30eHbwQfHv3Bwr9TcUFAWA bZHF5ttOk7fw2a491xVTix5eWi5aE/V+r/vu0rro9bYVW5JbmTHecmehx0hgS8A+rq 79+cznJKjhjiDxebJ1S7Xv1gq14XuXVziaRHDTzA= Received: from mchehab by mail.kernel.org with local (Exim 4.94) (envelope-from ) id 1kNc6f-001XIy-MN; 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 04/52] scripts: kernel-doc: make it more compatible with Sphinx 3.x Date: Wed, 30 Sep 2020 15:24:27 +0200 Message-Id: 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-doc@vger.kernel.org With Sphinx 3.x, the ".. c:type:" tag was changed to accept either: .. c:type:: typedef-like declaration .. c:type:: name Using it for other types (including functions) don't work anymore. So, there are newer tags for macro, enum, struct, union, and others, which doesn't exist on older versions. Add a check for the Sphinx version and change the produced tags accordingly. Signed-off-by: Mauro Carvalho Chehab --- scripts/kernel-doc | 71 ++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 65 insertions(+), 6 deletions(-) diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 724528f4b7d6..3efc06d6f82d 100755 --- a/scripts/kernel-doc +++ b/scripts/kernel-doc @@ -271,6 +271,8 @@ if ($#ARGV == -1) { } my $kernelversion; +my $sphinx_major; + my $dohighlight = ""; my $verbose = 0; @@ -465,6 +467,43 @@ while ($ARGV[0] =~ m/^--?(.*)/) { # continue execution near EOF; +# The C domain dialect changed on Sphinx 3. So, we need to check the +# version in order to produce the right tags. +sub findprog($) +{ + foreach(split(/:/, $ENV{PATH})) { + return "$_/$_[0]" if(-x "$_/$_[0]"); + } +} + +sub get_sphinx_version() +{ + my $ver; + my $major = 1; + + my $cmd = "sphinx-build"; + if (!findprog($cmd)) { + my $cmd = "sphinx-build3"; + return $major if (!findprog($cmd)); + } + + open IN, "$cmd --version 2>&1 |"; + while () { + if (m/^\s*sphinx-build\s+([\d]+)\.([\d\.]+)(\+\/[\da-f]+)?$/) { + $major=$1; + last; + } + # Sphinx 1.2.x uses a different format + if (m/^\s*Sphinx.*\s+([\d]+)\.([\d\.]+)$/) { + $major=$1; + last; + } + } + close IN; + + return $major; +} + # get kernel version from env sub get_kernel_version() { my $version = 'unknown kernel version'; @@ -848,7 +887,11 @@ sub output_function_rst(%) { my $start = ""; if ($args{'typedef'}) { - print ".. c:type:: ". $args{'function'} . "\n\n"; + if ($sphinx_major < 3) { + print ".. c:type:: ". $args{'function'} . "\n\n"; + } else { + print ".. c:function:: ". $args{'function'} . "\n\n"; + } print_lineno($declaration_start_line); print " **Typedef**: "; $lineprefix = ""; @@ -938,9 +981,14 @@ sub output_enum_rst(%) { my ($parameter); my $oldprefix = $lineprefix; my $count; - my $name = "enum " . $args{'enum'}; - print "\n\n.. c:type:: " . $name . "\n\n"; + if ($sphinx_major < 3) { + my $name = "enum " . $args{'enum'}; + print "\n\n.. c:type:: " . $name . "\n\n"; + } else { + my $name = $args{'enum'}; + print "\n\n.. c:enum:: " . $name . "\n\n"; + } print_lineno($declaration_start_line); $lineprefix = " "; output_highlight_rst($args{'purpose'}); @@ -966,8 +1014,13 @@ sub output_typedef_rst(%) { my %args = %{$_[0]}; my ($parameter); my $oldprefix = $lineprefix; - my $name = "typedef " . $args{'typedef'}; + my $name; + if ($sphinx_major < 3) { + $name = "typedef " . $args{'typedef'}; + } else { + $name = $args{'typedef'}; + } print "\n\n.. c:type:: " . $name . "\n\n"; print_lineno($declaration_start_line); $lineprefix = " "; @@ -982,9 +1035,14 @@ sub output_struct_rst(%) { my %args = %{$_[0]}; my ($parameter); my $oldprefix = $lineprefix; - my $name = $args{'type'} . " " . $args{'struct'}; - print "\n\n.. c:type:: " . $name . "\n\n"; + if ($sphinx_major < 3) { + my $name = $args{'type'} . " " . $args{'struct'}; + print "\n\n.. c:type:: " . $name . "\n\n"; + } else { + my $name = $args{'struct'}; + print "\n\n.. c:struct:: " . $name . "\n\n"; + } print_lineno($declaration_start_line); $lineprefix = " "; output_highlight_rst($args{'purpose'}); @@ -2235,6 +2293,7 @@ sub process_file($) { } +$sphinx_major = get_sphinx_version(); $kernelversion = get_kernel_version(); # generate a sequence of code that will splice in highlighting information -- 2.26.2