Commit efa44475 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab
Browse files

scripts: kernel-doc: make it more compatible with Sphinx 3.x 



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: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
parent d38c8cfb

scripts/kernel-doc

+65 −6
Original line number Diff line number Diff line
@@ -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 (<IN>) {

		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'}) {

	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'};



    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'};



    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

CRA Git | Maintained and supported by SUSTech CRA and CCSE