[PATCH 0/5] Some fixes for ABI documentation

[PATCH 0/5] Some fixes for ABI documentation

[Mauro Carvalho Chehab]

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

[PATCH 1/5] docs: ABI: sysfs-driver-dma-ioatdma: what starts with /sys

[Mauro Carvalho Chehab]

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

[PATCH 2/5] docs: ABI: sysfs-class-net: fix a typo

[Mauro Carvalho Chehab]

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

[PATCH 3/5] docs: leds: index.rst: add a missing file

[Mauro Carvalho Chehab]

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

[PATCH 4/5] scripts: get_abi.pl: Don't let ABI files to create subtitles

[Mauro Carvalho Chehab]

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

[PATCH 5/5] scripts: get_api.pl: Add sub-titles to ABI output

[Mauro Carvalho Chehab]

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