diff options
author | Peter Maydell <peter.maydell@linaro.org> | 2020-04-14 13:50:41 +0100 |
---|---|---|
committer | Peter Maydell <peter.maydell@linaro.org> | 2020-04-14 17:15:33 +0100 |
commit | 152d1967f650f67b7ece3a5dda77d48069d72647 (patch) | |
tree | 4abda175287777901c8b39a502218b776043c593 /scripts | |
parent | a62d563796e369b910073eeec02d604f23dcbe89 (diff) | |
download | qemu-152d1967f650f67b7ece3a5dda77d48069d72647.zip qemu-152d1967f650f67b7ece3a5dda77d48069d72647.tar.gz qemu-152d1967f650f67b7ece3a5dda77d48069d72647.tar.bz2 |
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>
Diffstat (limited to 'scripts')
-rwxr-xr-x | scripts/kernel-doc | 16 |
1 files changed, 15 insertions, 1 deletions
diff --git a/scripts/kernel-doc b/scripts/kernel-doc index 8dc30e0..030b5c8 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'}); |