Commit 93351d41 authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab
Browse files

scripts: kernel-doc: allow passing desired Sphinx C domain dialect 



When kernel-doc is called via kerneldoc.py, there's no need to
auto-detect the Sphinx version, as the Sphinx module already
knows it. So, add an optional parameter to allow changing the
Sphinx dialect.

As kernel-doc can also be manually called, keep the auto-detection
logic if the parameter was not specified. On such case, emit
a warning if sphinx-build can't be found at PATH.

I ended using a suggestion from Joe for using a more readable
regex, instead of using a complex one with a hidden group like:

	m/^(\d+)\.(\d+)(?:\.?(\d+)?)/

in order to get the optional <patch> argument.

Thanks-to: Joe Perches <joe@perches.com>
Suggested-by: default avatarJonathan Corbet <corbet@lwn.net>
Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+huawei@kernel.org>
parent ed8348e2

Documentation/sphinx/kerneldoc.py

+5 −0
Original line number Diff line number Diff line
@@ -70,6 +70,11 @@ class KernelDocDirective(Directive): 
        env = self.state.document.settings.env

        cmd = [env.config.kerneldoc_bin, '-rst', '-enable-lineno']



	# Pass the version string to kernel-doc, as it needs to use a different

	# dialect, depending what the C domain supports for each specific

	# Sphinx versions

        cmd += ['-sphinx-version', sphinx.__version__]



        filename = env.config.kerneldoc_srctree + '/' + self.arguments[0]

        export_file_patterns = []

scripts/kernel-doc

+43 −8
Original line number Diff line number Diff line
@@ -56,6 +56,13 @@ Output format selection (mutually exclusive): 
  -rst			Output reStructuredText format.

  -none			Do not output documentation, only warnings.



Output format selection modifier (affects only ReST output):



  -sphinx-version	Use the ReST C domain dialect compatible with an

			specific Sphinx Version.

			If not specified, kernel-doc will auto-detect using

			the sphinx-build version found on PATH.



Output selection (mutually exclusive):

  -export		Only output documentation for symbols that have been

			exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
@@ -270,7 +277,7 @@ if ($#ARGV == -1) { 
}



my $kernelversion;

my $sphinx_major;

my ($sphinx_major, $sphinx_minor, $sphinx_patch);



my $dohighlight = "";
@@ -457,6 +464,23 @@ while ($ARGV[0] =~ m/^--?(.*)/) { 
	    $enable_lineno = 1;

    } elsif ($cmd eq 'show-not-found') {

	$show_not_found = 1;  # A no-op but don't fail

    } elsif ($cmd eq "sphinx-version") {

	my $ver_string = shift @ARGV;

	if ($ver_string =~ m/^(\d+)(\.\d+)?(\.\d+)?/) {

	    $sphinx_major = $1;

	    if (defined($2)) {

		$sphinx_minor = substr($2,1);

	    } else {

		$sphinx_minor = 0;

	    }

	    if (defined($3)) {

		$sphinx_patch = substr($3,1)

	    } else {

		$sphinx_patch = 0;

	    }

	} else {

	    die "Sphinx version should either major.minor or major.minor.patch format\n";

	}

    } else {

	# Unknown argument

        usage();
@@ -477,29 +501,37 @@ sub findprog($) 
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));

		if (!findprog($cmd)) {

			$sphinx_major = 1;

			$sphinx_minor = 2;

			$sphinx_patch = 0;

			printf STDERR "Warning: Sphinx version not found. Using default (Sphinx version %d.%d.%d)\n",

			       $sphinx_major, $sphinx_minor, $sphinx_patch;

			return;

		}

	}



	open IN, "$cmd --version 2>&1 |";

	while (<IN>) {

		if (m/^\s*sphinx-build\s+([\d]+)\.([\d\.]+)(\+\/[\da-f]+)?$/) {

			$major=$1;

			$sphinx_major = $1;

			$sphinx_minor = $2;

			$sphinx_patch = $3;

			last;

		}

		# Sphinx 1.2.x uses a different format

		if (m/^\s*Sphinx.*\s+([\d]+)\.([\d\.]+)$/) {

			$major=$1;

			$sphinx_major = $1;

			$sphinx_minor = $2;

			$sphinx_patch = $3;

			last;

		}

	}

	close IN;



	return $major;

}



# get kernel version from env
@@ -2333,7 +2365,10 @@ sub process_file($) { 
}





$sphinx_major = get_sphinx_version();

if ($output_mode eq "rst") {

	get_sphinx_version() if (!$sphinx_major);

}



$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