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

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
...@@ -70,6 +70,11 @@ class KernelDocDirective(Directive): ...@@ -70,6 +70,11 @@ class KernelDocDirective(Directive):
env = self.state.document.settings.env env = self.state.document.settings.env
cmd = [env.config.kerneldoc_bin, '-rst', '-enable-lineno'] 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] filename = env.config.kerneldoc_srctree + '/' + self.arguments[0]
export_file_patterns = [] export_file_patterns = []
......
...@@ -56,6 +56,13 @@ Output format selection (mutually exclusive): ...@@ -56,6 +56,13 @@ Output format selection (mutually exclusive):
-rst Output reStructuredText format. -rst Output reStructuredText format.
-none Do not output documentation, only warnings. -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): Output selection (mutually exclusive):
-export Only output documentation for symbols that have been -export Only output documentation for symbols that have been
exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL() exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
...@@ -270,7 +277,7 @@ if ($#ARGV == -1) { ...@@ -270,7 +277,7 @@ if ($#ARGV == -1) {
} }
my $kernelversion; my $kernelversion;
my $sphinx_major; my ($sphinx_major, $sphinx_minor, $sphinx_patch);
my $dohighlight = ""; my $dohighlight = "";
...@@ -457,6 +464,23 @@ while ($ARGV[0] =~ m/^--?(.*)/) { ...@@ -457,6 +464,23 @@ while ($ARGV[0] =~ m/^--?(.*)/) {
$enable_lineno = 1; $enable_lineno = 1;
} elsif ($cmd eq 'show-not-found') { } elsif ($cmd eq 'show-not-found') {
$show_not_found = 1; # A no-op but don't fail $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 { } else {
# Unknown argument # Unknown argument
usage(); usage();
...@@ -477,29 +501,37 @@ sub findprog($) ...@@ -477,29 +501,37 @@ sub findprog($)
sub get_sphinx_version() sub get_sphinx_version()
{ {
my $ver; my $ver;
my $major = 1;
my $cmd = "sphinx-build"; my $cmd = "sphinx-build";
if (!findprog($cmd)) { if (!findprog($cmd)) {
my $cmd = "sphinx-build3"; 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 |"; open IN, "$cmd --version 2>&1 |";
while (<IN>) { while (<IN>) {
if (m/^\s*sphinx-build\s+([\d]+)\.([\d\.]+)(\+\/[\da-f]+)?$/) { if (m/^\s*sphinx-build\s+([\d]+)\.([\d\.]+)(\+\/[\da-f]+)?$/) {
$major=$1; $sphinx_major = $1;
$sphinx_minor = $2;
$sphinx_patch = $3;
last; last;
} }
# Sphinx 1.2.x uses a different format # Sphinx 1.2.x uses a different format
if (m/^\s*Sphinx.*\s+([\d]+)\.([\d\.]+)$/) { if (m/^\s*Sphinx.*\s+([\d]+)\.([\d\.]+)$/) {
$major=$1; $sphinx_major = $1;
$sphinx_minor = $2;
$sphinx_patch = $3;
last; last;
} }
} }
close IN; close IN;
return $major;
} }
# get kernel version from env # get kernel version from env
...@@ -2333,7 +2365,10 @@ sub process_file($) { ...@@ -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(); $kernelversion = get_kernel_version();
# generate a sequence of code that will splice in highlighting information # generate a sequence of code that will splice in highlighting information
......
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment