aboutsummaryrefslogtreecommitdiff
path: root/scripts/kernel-doc
diff options
context:
space:
mode:
authorMauro Carvalho Chehab <mchehab+huawei@kernel.org>2020-11-17 17:52:59 +0100
committerPaolo Bonzini <pbonzini@redhat.com>2020-12-10 12:15:22 -0500
commit6d3a3cfc2f1ca323b671ecdb48f4b9ec73583ea4 (patch)
treef570202c9bbf65554355c7bad5b43e06a3285731 /scripts/kernel-doc
parent46ae6e8f8225cc8e1aef13831e850154f3fd8ae6 (diff)
downloadqemu-6d3a3cfc2f1ca323b671ecdb48f4b9ec73583ea4.zip
qemu-6d3a3cfc2f1ca323b671ecdb48f4b9ec73583ea4.tar.gz
qemu-6d3a3cfc2f1ca323b671ecdb48f4b9ec73583ea4.tar.bz2
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: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com> Message-Id: <20201117165312.118257-17-pbonzini@redhat.com> Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Diffstat (limited to 'scripts/kernel-doc')
-rwxr-xr-xscripts/kernel-doc71
1 files changed, 65 insertions, 6 deletions
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 60f75cd..771367a 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 (<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'}) {
- 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