mirrors/qemu
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

scripts: kernel-doc: use a less pedantic markup for funcs on Sphinx 3.x

Browse Source 
Unfortunately, Sphinx 3.x parser for c functions is too pedantic:

	https://github.com/sphinx-doc/sphinx/issues/8241

While it could be relaxed with some configurations, there are
several corner cases that it would make it hard to maintain,
and will require teaching conf.py about several macros.

So, let's instead use the :c:macro notation. This will
produce an output that it is not as nice as currently, but it
should still be acceptable, and will provide cross-references,
removing thousands of warnings when building with newer
versions of Sphinx.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
Message-Id: <20201117165312.118257-18-pbonzini@redhat.com>
Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>
This commit is contained in:
Mauro Carvalho Chehab 2020-11-17 17:53:00 +01:00 committed by Paolo Bonzini
parent 6d3a3cfc2f
commit 60ef7c1801
1 changed files with 24 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
scripts/kernel-doc
View File

@ -886,12 +886,9 @@ sub output_function_rst(%) {
my $oldprefix = $lineprefix; my $oldprefix = $lineprefix;
my $start = ""; my $start = "";
if ($args{'typedef'}) {
if ($sphinx_major < 3) { if ($sphinx_major < 3) {
if ($args{'typedef'}) {
print ".. c:type:: ". $args{'function'} . "\n\n"; print ".. c:type:: ". $args{'function'} . "\n\n";
} else {
print ".. c:function:: ". $args{'function'} . "\n\n";
}
print_lineno($declaration_start_line); print_lineno($declaration_start_line);
print " **Typedef**: "; print " **Typedef**: ";
$lineprefix = ""; $lineprefix = "";
@ -900,6 +897,19 @@ sub output_function_rst(%) {
} else { } else {
print ".. c:function:: "; print ".. c:function:: ";
} }
} else {
print ".. c:macro:: ". $args{'function'} . "\n\n";
if ($args{'typedef'}) {
print_lineno($declaration_start_line);
print " **Typedef**: ";
$lineprefix = "";
output_highlight_rst($args{'purpose'});
$start = "\n\n**Syntax**\n\n ``";
} else {
print "``";
}
}
if ($args{'functiontype'} ne "") { if ($args{'functiontype'} ne "") {
$start .= $args{'functiontype'} . " " . $args{'function'} . " ("; $start .= $args{'functiontype'} . " " . $args{'function'} . " (";
} else { } else {
@ -925,7 +935,11 @@ sub output_function_rst(%) {
if ($args{'typedef'}) { if ($args{'typedef'}) {
print ");``\n\n"; print ");``\n\n";
} else { } else {
if ($sphinx_major < 3) {
print ")\n\n"; print ")\n\n";
} else {
print ")``\n";
}
print_lineno($declaration_start_line); print_lineno($declaration_start_line);
$lineprefix = " "; $lineprefix = " ";
output_highlight_rst($args{'purpose'}); output_highlight_rst($args{'purpose'});