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.1 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 78E32C2D0A3 for ; Tue, 13 Oct 2020 11:54:49 +0000 (UTC) Received: from vger.kernel.org (vger.kernel.org [23.128.96.18]) by mail.kernel.org (Postfix) with ESMTP id 2EB5020E65 for ; Tue, 13 Oct 2020 11:54:49 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1602590089; bh=V+7OC5N01urmt6Emf3gt8+IiL5ChKdmodgxNP6tpU1g=; h=From:To:Cc:Subject:Date:In-Reply-To:References:List-ID:From; b=aDoDIBFN1uLfaU7/Q9h82o9wl0r3fboJ8GOja8gFN2EREG4/HBw+pkX85V79r9yjx Xw2gLRM+yohANoaV4jEXx6NmvwFrG29NtKBHsa7C+VQ+I/jjM6sDG3KG0KeR1uV9Kv YGxLsLNsqGJuJ9hgAI34EQTKo5LrzDqD1Y8Ns+0c= Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727630AbgJMLyr (ORCPT ); Tue, 13 Oct 2020 07:54:47 -0400 Received: from mail.kernel.org ([198.145.29.99]:57142 "EHLO mail.kernel.org" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727297AbgJMLyk (ORCPT ); Tue, 13 Oct 2020 07:54:40 -0400 Received: from mail.kernel.org (ip5f5ad5b2.dynamic.kabel-deutschland.de [95.90.213.178]) (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 7594720870; Tue, 13 Oct 2020 11:54:39 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=default; t=1602590079; bh=V+7OC5N01urmt6Emf3gt8+IiL5ChKdmodgxNP6tpU1g=; h=From:To:Cc:Subject:Date:In-Reply-To:References:From; b=R/cALk6bvMfjuEAFNiTCs//57XePcLwqNJWAXvKGog2YcIlRg6DUGJaGRcvCP2y4N svVAvAdI4PcRi3NgPWK/fIEWoq4Xz6KfnQMrYmywOFKuGDqR7RMJ4GTgkA8kNJx4f/ XD8Zip8ugN0XdsF1nJFt4Bdj5A97RvkjWuzN9IlQ= Received: from mchehab by mail.kernel.org with local (Exim 4.94) (envelope-from ) id 1kSIt3-006CTB-4k; Tue, 13 Oct 2020 13:54:37 +0200 From: Mauro Carvalho Chehab To: Linux Doc Mailing List Cc: Mauro Carvalho Chehab , "Jonathan Corbet" , linux-kernel@vger.kernel.org Subject: [PATCH v6 02/80] scripts: kernel-doc: make it more compatible with Sphinx 3.x Date: Tue, 13 Oct 2020 13:53:17 +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-kernel@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 adc05406c68e..096317ef2e97 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'}); @@ -2242,6 +2300,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