OpenE2K/qemu-e2k
13
4
Fork 0
Code Issues 4 Pull Requests Projects 2 Releases Activity

kernel-doc: Use c:struct for Sphinx 3.0 and later

Browse Source 
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:
Peter Maydell 2020-04-14 13:50:41 +01:00
parent a62d563796
commit 152d1967f6
2 changed files with 16 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/sphinx/kerneldoc.py
View File

@ -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:

16
scripts/kernel-doc
View File

@ -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'});