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>
This commit is contained in:
parent
a62d563796
commit
152d1967f6
@ -99,6 +99,7 @@ class KernelDocDirective(Directive):
|
|||||||
env.note_dependency(os.path.abspath(f))
|
env.note_dependency(os.path.abspath(f))
|
||||||
cmd += ['-export-file', f]
|
cmd += ['-export-file', f]
|
||||||
|
|
||||||
|
cmd += ['-sphinx-version', sphinx.__version__]
|
||||||
cmd += [filename]
|
cmd += [filename]
|
||||||
|
|
||||||
try:
|
try:
|
||||||
|
@ -71,6 +71,8 @@ Output selection (mutually exclusive):
|
|||||||
DOC: sections. May be specified multiple times.
|
DOC: sections. May be specified multiple times.
|
||||||
|
|
||||||
Output selection modifiers:
|
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.
|
-no-doc-sections Do not output DOC: sections.
|
||||||
-enable-lineno Enable output of #define LINENO lines. Only works with
|
-enable-lineno Enable output of #define LINENO lines. Only works with
|
||||||
reStructuredText format.
|
reStructuredText format.
|
||||||
@ -286,6 +288,7 @@ use constant {
|
|||||||
};
|
};
|
||||||
my $output_selection = OUTPUT_ALL;
|
my $output_selection = OUTPUT_ALL;
|
||||||
my $show_not_found = 0; # No longer used
|
my $show_not_found = 0; # No longer used
|
||||||
|
my $sphinx_version = "0.0"; # if not specified, assume old
|
||||||
|
|
||||||
my @export_file_list;
|
my @export_file_list;
|
||||||
|
|
||||||
@ -436,6 +439,8 @@ 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') {
|
||||||
|
$sphinx_version = shift @ARGV;
|
||||||
} else {
|
} else {
|
||||||
# Unknown argument
|
# Unknown argument
|
||||||
usage();
|
usage();
|
||||||
@ -963,7 +968,16 @@ sub output_struct_rst(%) {
|
|||||||
my $oldprefix = $lineprefix;
|
my $oldprefix = $lineprefix;
|
||||||
my $name = $args{'type'} . " " . $args{'struct'};
|
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);
|
print_lineno($declaration_start_line);
|
||||||
$lineprefix = " ";
|
$lineprefix = " ";
|
||||||
output_highlight_rst($args{'purpose'});
|
output_highlight_rst($args{'purpose'});
|
||||||
|
Loading…
Reference in New Issue
Block a user