summaryrefslogtreecommitdiff
path: root/scripts
diff options
context:
space:
mode:
authorMauro Carvalho Chehab <mchehab+huawei@kernel.org>2020-10-04 09:44:28 +0200
committerMauro Carvalho Chehab <mchehab+huawei@kernel.org>2020-10-15 07:49:36 +0200
commit93351d4196802b3ee01074d96df47b73716984ba (patch)
treead992a9d39fd6513dd719a418d6792906ecff47e /scripts
parented8348e23abce79780f3b679c74a48bcdc47c947 (diff)
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: Jonathan Corbet <corbet@lwn.net> Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Diffstat (limited to 'scripts')
-rwxr-xr-xscripts/kernel-doc51
1 files changed, 43 insertions, 8 deletions
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 09e3e78b9723..ed32883c3221 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -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