* [PATCH 0/5] Some fixes for ABI documentation
[not found] <ff1301ed-6040-3aac-c057-7f37184604d3@infradead.org>
@ 2020-11-02 10:32 ` Mauro Carvalho Chehab
2020-11-02 10:32 ` [PATCH 1/5] docs: ABI: sysfs-driver-dma-ioatdma: what starts with /sys Mauro Carvalho Chehab
` (4 more replies)
0 siblings, 5 replies; 6+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-02 10:32 UTC (permalink / raw)
To: Linux Doc Mailing List, Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, linux-kernel, Jonathan Corbet,
Randy Dunlap, Linus Torvalds, Andrew Lunn, Cezary Rojewski,
Dan Murphy, Ilya Dryomov, Jacek Anaszewski, Oded Gabbay, Tom Rix,
Vaibhav Jain
Hi Greg,
This small series contain fixes against Kernel 5.10-rc2.
It is meant to address the issue reported by Randy, with regards
to some "SEVERE" docutils warnings that it is causing the build
to fail for him.
I was not able to reproduce the bug myself, but fixing it is easy.
While here, I noticed a few typos at a few sysfs ABI entries.
The first two patches address them.
The third patch fixes a small issue: I added a new ReST file
at the ABI series, but the index file didn't receive the update.
The forth patch is the one that actually fix the reported issue.
While here, I added small change at get_abi.pl, for it to generate
some index entries for the symbols. That sounded to me a
natural change after having patch 4 removing some ABI indexes.
This patch should make life easier for people looking for a symbol
inside the ABI books.
Mauro Carvalho Chehab (5):
docs: ABI: sysfs-driver-dma-ioatdma: what starts with /sys
docs: ABI: sysfs-class-net: fix a typo
docs: leds: index.rst: add a missing file
scripts: get_abi.pl: Don't let ABI files to create subtitles
scripts: get_api.pl: Add sub-titles to ABI output
.../ABI/stable/sysfs-driver-dma-ioatdma | 10 ++++----
Documentation/ABI/testing/sysfs-class-net | 2 +-
Documentation/leds/index.rst | 1 +
scripts/get_abi.pl | 23 +++++++++++++++++++
4 files changed, 30 insertions(+), 6 deletions(-)
--
2.26.2
^ permalink raw reply [flat|nested] 6+ messages in thread
* [PATCH 1/5] docs: ABI: sysfs-driver-dma-ioatdma: what starts with /sys
2020-11-02 10:32 ` [PATCH 0/5] Some fixes for ABI documentation Mauro Carvalho Chehab
@ 2020-11-02 10:32 ` Mauro Carvalho Chehab
2020-11-02 10:32 ` [PATCH 2/5] docs: ABI: sysfs-class-net: fix a typo Mauro Carvalho Chehab
` (3 subsequent siblings)
4 siblings, 0 replies; 6+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-02 10:32 UTC (permalink / raw)
To: Linux Doc Mailing List, Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Jonathan Corbet, Linus Torvalds,
Linux Kernel Mailing List, Randy Dunlap
This is the only file where the /sys doesn't start with
a /.
So, rename them to:
sys -> /sys
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/ABI/stable/sysfs-driver-dma-ioatdma | 10 +++++-----
1 file changed, 5 insertions(+), 5 deletions(-)
diff --git a/Documentation/ABI/stable/sysfs-driver-dma-ioatdma b/Documentation/ABI/stable/sysfs-driver-dma-ioatdma
index 420c1d09e42f..3a4e2cd0ddcc 100644
--- a/Documentation/ABI/stable/sysfs-driver-dma-ioatdma
+++ b/Documentation/ABI/stable/sysfs-driver-dma-ioatdma
@@ -1,29 +1,29 @@
-What: sys/devices/pciXXXX:XX/0000:XX:XX.X/dma/dma<n>chan<n>/quickdata/cap
+What: /sys/devices/pciXXXX:XX/0000:XX:XX.X/dma/dma<n>chan<n>/quickdata/cap
Date: December 3, 2009
KernelVersion: 2.6.32
Contact: dmaengine@vger.kernel.org
Description: Capabilities the DMA supports.Currently there are DMA_PQ, DMA_PQ_VAL,
DMA_XOR,DMA_XOR_VAL,DMA_INTERRUPT.
-What: sys/devices/pciXXXX:XX/0000:XX:XX.X/dma/dma<n>chan<n>/quickdata/ring_active
+What: /sys/devices/pciXXXX:XX/0000:XX:XX.X/dma/dma<n>chan<n>/quickdata/ring_active
Date: December 3, 2009
KernelVersion: 2.6.32
Contact: dmaengine@vger.kernel.org
Description: The number of descriptors active in the ring.
-What: sys/devices/pciXXXX:XX/0000:XX:XX.X/dma/dma<n>chan<n>/quickdata/ring_size
+What: /sys/devices/pciXXXX:XX/0000:XX:XX.X/dma/dma<n>chan<n>/quickdata/ring_size
Date: December 3, 2009
KernelVersion: 2.6.32
Contact: dmaengine@vger.kernel.org
Description: Descriptor ring size, total number of descriptors available.
-What: sys/devices/pciXXXX:XX/0000:XX:XX.X/dma/dma<n>chan<n>/quickdata/version
+What: /sys/devices/pciXXXX:XX/0000:XX:XX.X/dma/dma<n>chan<n>/quickdata/version
Date: December 3, 2009
KernelVersion: 2.6.32
Contact: dmaengine@vger.kernel.org
Description: Version of ioatdma device.
-What: sys/devices/pciXXXX:XX/0000:XX:XX.X/dma/dma<n>chan<n>/quickdata/intr_coalesce
+What: /sys/devices/pciXXXX:XX/0000:XX:XX.X/dma/dma<n>chan<n>/quickdata/intr_coalesce
Date: August 8, 2017
KernelVersion: 4.14
Contact: dmaengine@vger.kernel.org
--
2.26.2
^ permalink raw reply related [flat|nested] 6+ messages in thread
* [PATCH 2/5] docs: ABI: sysfs-class-net: fix a typo
2020-11-02 10:32 ` [PATCH 0/5] Some fixes for ABI documentation Mauro Carvalho Chehab
2020-11-02 10:32 ` [PATCH 1/5] docs: ABI: sysfs-driver-dma-ioatdma: what starts with /sys Mauro Carvalho Chehab
@ 2020-11-02 10:32 ` Mauro Carvalho Chehab
2020-11-02 10:32 ` [PATCH 3/5] docs: leds: index.rst: add a missing file Mauro Carvalho Chehab
` (2 subsequent siblings)
4 siblings, 0 replies; 6+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-02 10:32 UTC (permalink / raw)
To: Linux Doc Mailing List, Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Jonathan Corbet, Linus Torvalds,
Linux Kernel Mailing List, Randy Dunlap, Andrew Lunn,
Cezary Rojewski, Ilya Dryomov, Tom Rix
clas->class
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/ABI/testing/sysfs-class-net | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/ABI/testing/sysfs-class-net b/Documentation/ABI/testing/sysfs-class-net
index 7670012ae9b6..1f2002df5ba2 100644
--- a/Documentation/ABI/testing/sysfs-class-net
+++ b/Documentation/ABI/testing/sysfs-class-net
@@ -152,7 +152,7 @@ Description:
When an interface is under test, it cannot be expected
to pass packets as normal.
-What: /sys/clas/net/<iface>/duplex
+What: /sys/class/net/<iface>/duplex
Date: October 2009
KernelVersion: 2.6.33
Contact: netdev@vger.kernel.org
--
2.26.2
^ permalink raw reply related [flat|nested] 6+ messages in thread
* [PATCH 3/5] docs: leds: index.rst: add a missing file
2020-11-02 10:32 ` [PATCH 0/5] Some fixes for ABI documentation Mauro Carvalho Chehab
2020-11-02 10:32 ` [PATCH 1/5] docs: ABI: sysfs-driver-dma-ioatdma: what starts with /sys Mauro Carvalho Chehab
2020-11-02 10:32 ` [PATCH 2/5] docs: ABI: sysfs-class-net: fix a typo Mauro Carvalho Chehab
@ 2020-11-02 10:32 ` Mauro Carvalho Chehab
2020-11-02 10:32 ` [PATCH 4/5] scripts: get_abi.pl: Don't let ABI files to create subtitles Mauro Carvalho Chehab
2020-11-02 10:32 ` [PATCH 5/5] scripts: get_api.pl: Add sub-titles to ABI output Mauro Carvalho Chehab
4 siblings, 0 replies; 6+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-02 10:32 UTC (permalink / raw)
To: Linux Doc Mailing List, Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Jonathan Corbet, Linus Torvalds,
Linux Kernel Mailing List, Randy Dunlap, Dan Murphy,
Jacek Anaszewski
Changeset 26a07553041e ("docs: ABI: sysfs-class-led-trigger-pattern: remove hw_pattern duplication")
didn't include the needed changes at index.rst.
Fixes: 26a07553041e ("docs: ABI: sysfs-class-led-trigger-pattern: remove hw_pattern duplication")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/leds/index.rst | 1 +
1 file changed, 1 insertion(+)
diff --git a/Documentation/leds/index.rst b/Documentation/leds/index.rst
index 53e6090454af..e5d63b940045 100644
--- a/Documentation/leds/index.rst
+++ b/Documentation/leds/index.rst
@@ -25,3 +25,4 @@ LEDs
leds-lp5562
leds-lp55xx
leds-mlxcpld
+ leds-sc27xx
--
2.26.2
^ permalink raw reply related [flat|nested] 6+ messages in thread
* [PATCH 4/5] scripts: get_abi.pl: Don't let ABI files to create subtitles
2020-11-02 10:32 ` [PATCH 0/5] Some fixes for ABI documentation Mauro Carvalho Chehab
` (2 preceding siblings ...)
2020-11-02 10:32 ` [PATCH 3/5] docs: leds: index.rst: add a missing file Mauro Carvalho Chehab
@ 2020-11-02 10:32 ` Mauro Carvalho Chehab
2020-11-02 10:32 ` [PATCH 5/5] scripts: get_api.pl: Add sub-titles to ABI output Mauro Carvalho Chehab
4 siblings, 0 replies; 6+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-02 10:32 UTC (permalink / raw)
To: Linux Doc Mailing List, Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Jonathan Corbet, Linus Torvalds,
Linux Kernel Mailing List, Randy Dunlap, Cezary Rojewski,
Oded Gabbay
The ReST output should only contain documentation titles
automatically created by the script.
There are two reasons for that:
1) Consistency.
just a handful ABI docs define titles
2) To avoid critical errors.
Docutils (which is the basis for Sphinx) allows a free
assign of documentation title markups. So, one document
could be doing things like:
Level 1
=======
Level 2
-------
While another one could do the reverse:
Level 1
-------
Level 2
=======
But the same document can't mix.
As the output of get_abi.pl will join contents from multiple
files, if they don't define the levels on a consistent errors,
errors like this can happen:
Sphinx parallel build error:
docutils.utils.SystemMessage: /home/rdunlap/lnx/lnx-510-rc2/Documentation/ABI/testing/sysfs-bus-rapidio:2: (SEVERE/4) Title level inconsistent:
Attributes Common for All RapidIO Devices
-----------------------------------------
Which cause some versions of Sphinx to go into an endless
loop.
It should be noticed that an alternative to that would
be to replace all title occurrences by a single markup,
but that will make the parser more complex, and, due to
(1) it would generate an inconsistent output.
So, better to just remove the titles defined at the ABI
files from the output.
Reported-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
scripts/get_abi.pl | 6 ++++++
1 file changed, 6 insertions(+)
diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index 2cb592f8eba4..459f169f834c 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -352,6 +352,12 @@ sub output_rest {
if (!($desc =~ /^\s*$/)) {
if ($description_is_rst) {
+ # Remove title markups from the description
+ # Having titles inside ABI files will only work if extra
+ # care would be taken in order to strictly follow the same
+ # level order for each markup.
+ $desc =~ s/\n[\-\*\=\^\~]+\n/\n\n/g;
+
# Enrich text by creating cross-references
$desc =~ s,Documentation/(?!devicetree)(\S+)\.rst,:doc:`/$1`,g;
--
2.26.2
^ permalink raw reply related [flat|nested] 6+ messages in thread
* [PATCH 5/5] scripts: get_api.pl: Add sub-titles to ABI output
2020-11-02 10:32 ` [PATCH 0/5] Some fixes for ABI documentation Mauro Carvalho Chehab
` (3 preceding siblings ...)
2020-11-02 10:32 ` [PATCH 4/5] scripts: get_abi.pl: Don't let ABI files to create subtitles Mauro Carvalho Chehab
@ 2020-11-02 10:32 ` Mauro Carvalho Chehab
4 siblings, 0 replies; 6+ messages in thread
From: Mauro Carvalho Chehab @ 2020-11-02 10:32 UTC (permalink / raw)
To: Linux Doc Mailing List, Greg Kroah-Hartman
Cc: Mauro Carvalho Chehab, Jonathan Corbet, Linus Torvalds,
Linux Kernel Mailing List, Randy Dunlap, Tom Rix, Vaibhav Jain
Instead of adding titles just for the files, add titles
for each part of the ABI output, in order to make easier
to search for a symbol there.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
scripts/get_abi.pl | 17 +++++++++++++++++
1 file changed, 17 insertions(+)
diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index 459f169f834c..68dab828a722 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -287,6 +287,8 @@ my $bondary = qr { (?<![\w\/\`\{])(?=[\w\/\`\{])|(?<=[\w\/\`\{])(?![\w\/\`\{]) }
sub output_rest {
create_labels();
+ my $part = "";
+
foreach my $what (sort {
($data{$a}->{type} eq "File") cmp ($data{$b}->{type} eq "File") ||
$a cmp $b
@@ -306,6 +308,21 @@ sub output_rest {
$w =~ s/([\(\)\_\-\*\=\^\~\\])/\\$1/g;
if ($type ne "File") {
+ my $cur_part = $what;
+ if ($what =~ '/') {
+ if ($what =~ m#^(\/?(?:[\w\-]+\/?){1,2})#) {
+ $cur_part = "Symbols under $1";
+ $cur_part =~ s,/$,,;
+ }
+ }
+
+ if ($cur_part ne "" && $part ne $cur_part) {
+ $part = $cur_part;
+ my $bar = $part;
+ $bar =~ s/./-/g;
+ print "$part\n$bar\n\n";
+ }
+
printf ".. _%s:\n\n", $data{$what}->{label};
my @names = split /, /,$w;
--
2.26.2
^ permalink raw reply related [flat|nested] 6+ messages in thread
end of thread, other threads:[~2020-11-02 10:32 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
[not found] <ff1301ed-6040-3aac-c057-7f37184604d3@infradead.org>
2020-11-02 10:32 ` [PATCH 0/5] Some fixes for ABI documentation Mauro Carvalho Chehab
2020-11-02 10:32 ` [PATCH 1/5] docs: ABI: sysfs-driver-dma-ioatdma: what starts with /sys Mauro Carvalho Chehab
2020-11-02 10:32 ` [PATCH 2/5] docs: ABI: sysfs-class-net: fix a typo Mauro Carvalho Chehab
2020-11-02 10:32 ` [PATCH 3/5] docs: leds: index.rst: add a missing file Mauro Carvalho Chehab
2020-11-02 10:32 ` [PATCH 4/5] scripts: get_abi.pl: Don't let ABI files to create subtitles Mauro Carvalho Chehab
2020-11-02 10:32 ` [PATCH 5/5] scripts: get_api.pl: Add sub-titles to ABI output Mauro Carvalho Chehab
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).