jcs.org / qemu
qemu with hax to log dma reads & writes jcs.org/2018/11/12/vfio
fork atom

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>

Peter Maydell 152d1967 a62d5637

+16 -1
+1
docs/sphinx/kerneldoc.py
··· 99 99 env.note_dependency(os.path.abspath(f)) 100 100 cmd += ['-export-file', f] 101 101 102 + cmd += ['-sphinx-version', sphinx.__version__] 102 103 cmd += [filename] 103 104 104 105 try:
+15 -1
scripts/kernel-doc
··· 71 71 DOC: sections. May be specified multiple times. 72 72 73 73 Output selection modifiers: 74 + -sphinx-version VER Generate rST syntax for the specified Sphinx version. 75 + Only works with reStructuredTextFormat. 74 76 -no-doc-sections Do not output DOC: sections. 75 77 -enable-lineno Enable output of #define LINENO lines. Only works with 76 78 reStructuredText format. ··· 286 288 }; 287 289 my $output_selection = OUTPUT_ALL; 288 290 my $show_not_found = 0; # No longer used 291 + my $sphinx_version = "0.0"; # if not specified, assume old 289 292 290 293 my @export_file_list; 291 294 ··· 436 439 $enable_lineno = 1; 437 440 } elsif ($cmd eq 'show-not-found') { 438 441 $show_not_found = 1; # A no-op but don't fail 442 + } elsif ($cmd eq 'sphinx-version') { 443 + $sphinx_version = shift @ARGV; 439 444 } else { 440 445 # Unknown argument 441 446 usage(); ··· 963 968 my $oldprefix = $lineprefix; 964 969 my $name = $args{'type'} . " " . $args{'struct'}; 965 970 966 - print "\n\n.. c:type:: " . $name . "\n\n"; 971 + # Sphinx 3.0 and up will emit warnings for "c:type:: struct Foo". 972 + # It wants to see "c:struct:: Foo" (and will add the word 'struct' in 973 + # the rendered output). 974 + if ((split(/\./, $sphinx_version))[0] >= 3) { 975 + my $sname = $name; 976 + $sname =~ s/^struct //; 977 + print "\n\n.. c:struct:: " . $sname . "\n\n"; 978 + } else { 979 + print "\n\n.. c:type:: " . $name . "\n\n"; 980 + } 967 981 print_lineno($declaration_start_line); 968 982 $lineprefix = " "; 969 983 output_highlight_rst($args{'purpose'});