[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[PULL 099/113] scripts: kernel-doc: use a less pedantic markup for funcs
From: |
Paolo Bonzini |
Subject: |
[PULL 099/113] scripts: kernel-doc: use a less pedantic markup for funcs on Sphinx 3.x |
Date: |
Wed, 2 Dec 2020 03:08:35 -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
- [PULL 102/113] scripts: kernel-doc: fix typedef identification, (continued)
- [PULL 102/113] scripts: kernel-doc: fix typedef identification, Paolo Bonzini, 2020/12/02
- [PULL 098/113] scripts: kernel-doc: make it more compatible with Sphinx 3.x, Paolo Bonzini, 2020/12/02
- [PULL 107/113] Revert "kernel-doc: Handle function typedefs without asterisks", Paolo Bonzini, 2020/12/02
- [PULL 104/113] scripts: kernel-doc: allow passing desired Sphinx C domain dialect, Paolo Bonzini, 2020/12/02
- [PULL 078/113] vl: extract softmmu/rtc.c, Paolo Bonzini, 2020/12/02
- [PULL 093/113] kernel-doc: include line numbers for function prototypes, Paolo Bonzini, 2020/12/02
- [PULL 106/113] scripts: kernel-doc: try to use c:function if possible, Paolo Bonzini, 2020/12/02
- [PULL 105/113] scripts: kernel-doc: fix line number handling, Paolo Bonzini, 2020/12/02
- [PULL 113/113] scripts: kernel-doc: remove unnecesssary change wrt Linux, Paolo Bonzini, 2020/12/02
- [PULL 111/113] scripts: kernel-doc: use :c:union when needed, Paolo Bonzini, 2020/12/02
- [PULL 099/113] scripts: kernel-doc: use a less pedantic markup for funcs on Sphinx 3.x,
Paolo Bonzini <=
- [PULL 065/113] vl: move CHECKPOINT_INIT after preconfig, Paolo Bonzini, 2020/12/02
- [PULL 091/113] scripts/kernel-doc: handle function pointer prototypes, Paolo Bonzini, 2020/12/02
- [PULL 101/113] scripts: kernel-doc: reimplement -nofunction argument, Paolo Bonzini, 2020/12/02
- [PULL 100/113] scripts: kernel-doc: fix troubles with line counts, Paolo Bonzini, 2020/12/02
- [PULL 109/113] scripts: kernel-doc: fix typedef parsing, Paolo Bonzini, 2020/12/02
- [PULL 108/113] Revert "kernel-doc: Handle function typedefs that return pointers", Paolo Bonzini, 2020/12/02
- [PULL 103/113] scripts: kernel-doc: don't mangle with parameter list, Paolo Bonzini, 2020/12/02
- [PULL 112/113] Revert "docs: temporarily disable the kernel-doc extension", Paolo Bonzini, 2020/12/02
- [PULL 110/113] scripts: kernel-doc: split typedef complex regex, Paolo Bonzini, 2020/12/02
- Re: [PULL 000/113] First batch of misc (i386, kernel-doc, memory, vl.c) changes for QEMU 6.0, no-reply, 2020/12/02