[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PATCH v2 18/32] scripts: kernel-doc: use a less pedantic markup for fun
From: |
Paolo Bonzini |
Subject: |
[PATCH v2 18/32] scripts: kernel-doc: use a less pedantic markup for funcs on Sphinx 3.x |
Date: |
Tue, 1 Dec 2020 05:34:48 -0500 |
From: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
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>
---
scripts/kernel-doc | 34 ++++++++++++++++++++++++----------
1 file changed, 24 insertions(+), 10 deletions(-)
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index 771367a6ab..75ddd3b5e6 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -886,19 +886,29 @@ sub output_function_rst(%) {
my $oldprefix = $lineprefix;
my $start = "";
- if ($args{'typedef'}) {
- if ($sphinx_major < 3) {
+ if ($sphinx_major < 3) {
+ if ($args{'typedef'}) {
print ".. c:type:: ". $args{'function'} . "\n\n";
+ print_lineno($declaration_start_line);
+ print " **Typedef**: ";
+ $lineprefix = "";
+ output_highlight_rst($args{'purpose'});
+ $start = "\n\n**Syntax**\n\n ``";
} else {
- print ".. c:function:: ". $args{'function'} . "\n\n";
+ print ".. c:function:: ";
}
- print_lineno($declaration_start_line);
- print " **Typedef**: ";
- $lineprefix = "";
- output_highlight_rst($args{'purpose'});
- $start = "\n\n**Syntax**\n\n ``";
} else {
- print ".. c:function:: ";
+ 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 "") {
$start .= $args{'functiontype'} . " " . $args{'function'} . " (";
@@ -925,7 +935,11 @@ sub output_function_rst(%) {
if ($args{'typedef'}) {
print ");``\n\n";
} else {
- print ")\n\n";
+ if ($sphinx_major < 3) {
+ print ")\n\n";
+ } else {
+ print ")``\n";
+ }
print_lineno($declaration_start_line);
$lineprefix = " ";
output_highlight_rst($args{'purpose'});
--
2.26.2
- [PATCH v2 21/32] scripts: kernel-doc: fix typedef identification, (continued)
- [PATCH v2 21/32] scripts: kernel-doc: fix typedef identification, Paolo Bonzini, 2020/12/01
- [PATCH v2 30/32] scripts: kernel-doc: use :c:union when needed, Paolo Bonzini, 2020/12/01
- [PATCH v2 32/32] scripts: kernel-doc: remove unnecesssary change wrt Linux, Paolo Bonzini, 2020/12/01
- [PATCH v2 31/32] Revert "docs: temporarily disable the kernel-doc extension", Paolo Bonzini, 2020/12/01
- [PATCH v2 17/32] scripts: kernel-doc: make it more compatible with Sphinx 3.x, Paolo Bonzini, 2020/12/01
- [PATCH v2 28/32] scripts: kernel-doc: fix typedef parsing, Paolo Bonzini, 2020/12/01
- [PATCH v2 18/32] scripts: kernel-doc: use a less pedantic markup for funcs on Sphinx 3.x,
Paolo Bonzini <=
- Re: [PATCH v2 00/32] kernel-doc: update from Linux 5.10, Peter Maydell, 2020/12/01