[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH for-5.0? 3/3] kernel-doc: Use c:struct for Sphinx 3.0 and later
From: |
Peter Maydell |
Subject: |
[PATCH for-5.0? 3/3] kernel-doc: Use c:struct for Sphinx 3.0 and later |
Date: |
Sat, 11 Apr 2020 19:29:34 +0100 |
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 <address@hidden>
---
docs/sphinx/kerneldoc.py | 1 +
scripts/kernel-doc | 16 +++++++++++++++-
2 files changed, 16 insertions(+), 1 deletion(-)
diff --git a/docs/sphinx/kerneldoc.py b/docs/sphinx/kerneldoc.py
index 1159405cb92..3e879402064 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 8dc30e01e58..030b5c8691f 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'});
--
2.20.1