aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorPeter Maydell <peter.maydell@linaro.org>2020-04-14 13:50:41 +0100
committerPeter Maydell <peter.maydell@linaro.org>2020-04-14 17:15:33 +0100
commit152d1967f650f67b7ece3a5dda77d48069d72647 (patch)
tree4abda175287777901c8b39a502218b776043c593
parenta62d563796e369b910073eeec02d604f23dcbe89 (diff)
downloadqemu-arm-152d1967f650f67b7ece3a5dda77d48069d72647.tar.gz
kernel-doc: Use c:struct for Sphinx 3.0 and later
The kernel-doc Sphinx plugin and associated script currently emit 'c:type' directives for "struct foo" documentation. Sphinx 3.0 warns about this: /home/petmay01/linaro/qemu-from-laptop/qemu/docs/../include/exec/memory.h:3: WARNING: Type must be either just a name or a typedef-like declaration. If just a name: Error in declarator or parameters Invalid C declaration: Expected identifier in nested name, got keyword: struct [error at 6] struct MemoryListener ------^ If typedef-like declaration: Error in declarator or parameters Invalid C declaration: Expected identifier in nested name. [error at 21] struct MemoryListener ---------------------^ because it wants us to use the new-in-3.0 'c:struct' instead. Plumb the Sphinx version through to the kernel-doc script and use it to select 'c:struct' for newer versions than 3.0. Fixes: LP:1872113 Signed-off-by: Peter Maydell <peter.maydell@linaro.org> Reviewed-by: Alex Bennée <alex.bennee@linaro.org>
-rw-r--r--docs/sphinx/kerneldoc.py1
-rwxr-xr-xscripts/kernel-doc16
2 files changed, 16 insertions, 1 deletions
diff --git a/docs/sphinx/kerneldoc.py b/docs/sphinx/kerneldoc.py
index 1159405cb9..3e87940206 100644
--- a/docs/sphinx/kerneldoc.py
+++ b/docs/sphinx/kerneldoc.py
@@ -99,6 +99,7 @@ class KernelDocDirective(Directive):
env.note_dependency(os.path.abspath(f))
cmd += ['-export-file', f]
+ cmd += ['-sphinx-version', sphinx.__version__]
cmd += [filename]
try:
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 8dc30e01e5..030b5c8691 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -71,6 +71,8 @@ Output selection (mutually exclusive):
DOC: sections. May be specified multiple times.
Output selection modifiers:
+ -sphinx-version VER Generate rST syntax for the specified Sphinx version.
+ Only works with reStructuredTextFormat.
-no-doc-sections Do not output DOC: sections.
-enable-lineno Enable output of #define LINENO lines. Only works with
reStructuredText format.
@@ -286,6 +288,7 @@ use constant {
};
my $output_selection = OUTPUT_ALL;
my $show_not_found = 0; # No longer used
+my $sphinx_version = "0.0"; # if not specified, assume old
my @export_file_list;
@@ -436,6 +439,8 @@ 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') {
+ $sphinx_version = shift @ARGV;
} else {
# Unknown argument
usage();
@@ -963,7 +968,16 @@ sub output_struct_rst(%) {
my $oldprefix = $lineprefix;
my $name = $args{'type'} . " " . $args{'struct'};
- print "\n\n.. c:type:: " . $name . "\n\n";
+ # Sphinx 3.0 and up will emit warnings for "c:type:: struct Foo".
+ # It wants to see "c:struct:: Foo" (and will add the word 'struct' in
+ # the rendered output).
+ if ((split(/\./, $sphinx_version))[0] >= 3) {
+ my $sname = $name;
+ $sname =~ s/^struct //;
+ print "\n\n.. c:struct:: " . $sname . "\n\n";
+ } else {
+ print "\n\n.. c:type:: " . $name . "\n\n";
+ }
print_lineno($declaration_start_line);
$lineprefix = " ";
output_highlight_rst($args{'purpose'});