Hi Greg,
As you proposed to give it a try on removing the escape code from the
script which parses the ReST file, I changed a few things there,
adding the capability of selectively enabling to output an ABI sub-dir
without escaping things that would crash Sphinx.
PS.: As for now this is just a RFC, I'm not getting the ABI file
maintainers, copying just LKML, linux-doc ML, plus you and Jon.
I also manually fixed the contents of ABI/stable, in order for it to
pass without causing troubles.
I added all patches from ABI and features at this branch:
https://git.linuxtv.org/mchehab/experimental.git/log/?h=abi_patches_v4.1
The html output is at https://www.infradead.org/~mchehab/rst_features/,
and you can see the resulting ABI guide on:
https://www.infradead.org/~mchehab/rst_features/admin-guide/abi.html
No Sphinx crashes/warnings happen when building it.
That's my personal notes about such work:
1) Documentation/ABI/stable/sysfs-class-infiniband
It had some title captions inside it, like:
Errors info:
-----------
For one of the "What:"
Sphinx is really pick with title markups. As the entire Documentation/stable is
parsed as if it were a single document, there should be a coherency on what
character is used to markup a level-one title. I mean, if one document uses:
foo
----
For the first level, all other documents should use "---...-" as well.
The alternative would be to have one entry for every single file at
Documentation/admin-guide/abi-*.rst, with, IMHO, it would be a lot
harder to maintain.
So, the best seems to let clear at ABI/README about how titles/subtitles
should be used inside files, if any.
2) Some documents there use a "Values:" tag, with is not defined as a
valid one at ABI/README. The script handles it as part of the description,
so no harm done;
3) Among the 47 files under ABI/stable, 14 of them names the file
contents, using a valid ReST markup for the document title. That is shown
at the index at:
https://www.infradead.org/~mchehab/rst_features/admin-guide/abi.html
- ABI stable symbols
- sysfs interface for Mellanox ConnectX HCA IB driver (mlx4)
- sysfs interface for Intel IB driver qib
- sysfs interface for Intel(R) X722 iWARP i40iw driver
- sysfs interface for QLogic qedr NIC Driver
- sysfs interface for NetEffect RNIC Low-Level iWARP driver (nes)
- sysfs interface for Cisco VIC (usNIC) Verbs Driver
- sysfs interface for Chelsio T3 RDMA Driver (cxgb3)
- sysfs interface for Chelsio T4/T5 RDMA driver (cxgb4)
- sysfs interface for Intel Omni-Path driver (HFI1)
- sysfs interface for VMware Paravirtual RDMA driver
- sysfs interface for Mellanox Connect-IB HCA driver mlx5
- sysfs interface for Emulex RoCE HCA Driver
- sysfs interface for Broadcom NetXtreme-E RoCE driver
- sysfs interface for Mellanox IB HCA low-level driver (mthca)
I liked that, but ideally all ABI files should either use it or not.
4) I was expecting to have troubles with asterisk characters inside the
ABI files. That was not the case: I had to escape just one occurrence on
a single file of the 47 ones inside ABI/stable.
-
My conclusion from this experiment is that it is worth cleaning the ABI
files for them to be parsed without needing to escape non-ReST compliant
parts of the ABI file.
Perhaps we could keep rst-compliant the stable, obsolete and removed
directories only, and gradually moving stuff from ABI/testing to ABI/stable,
while fixing them to be rst-compliant.
Mauro Carvalho Chehab (6):
get_abi.pl: fix parsing on ReST mode
ABI: sysfs-driver-mlxreg-io: fix the what fields
ABI: README: specify that files should be ReST compatible
ABI: stable: make files ReST compatible
docs: ABI: make it parse ABI/stable as ReST-compatible files
docs: abi: create a 2-depth index for ABI
Documentation/ABI/README | 10 +-
Documentation/ABI/stable/firewire-cdev | 4 +
Documentation/ABI/stable/sysfs-acpi-pmprofile | 22 +++--
Documentation/ABI/stable/sysfs-bus-firewire | 3 +
Documentation/ABI/stable/sysfs-bus-nvmem | 19 ++--
Documentation/ABI/stable/sysfs-bus-usb | 6 +-
.../ABI/stable/sysfs-class-backlight | 1 +
.../ABI/stable/sysfs-class-infiniband | 97 +++++++++++++------
Documentation/ABI/stable/sysfs-class-rfkill | 13 ++-
Documentation/ABI/stable/sysfs-class-tpm | 90 ++++++++---------
Documentation/ABI/stable/sysfs-devices | 5 +-
Documentation/ABI/stable/sysfs-driver-ib_srp | 1 +
.../ABI/stable/sysfs-driver-mlxreg-io | 45 ++++-----
.../ABI/stable/sysfs-firmware-efi-vars | 4 +
.../ABI/stable/sysfs-firmware-opal-dump | 5 +
.../ABI/stable/sysfs-firmware-opal-elog | 2 +
Documentation/ABI/stable/sysfs-hypervisor-xen | 3 +
Documentation/ABI/stable/vdso | 5 +-
Documentation/admin-guide/abi-stable.rst | 1 +
Documentation/admin-guide/abi.rst | 2 +-
Documentation/sphinx/kernel_abi.py | 9 +-
scripts/get_abi.pl | 30 +++---
22 files changed, 231 insertions(+), 146 deletions(-)
--
2.21.0
When the source ABI file is using ReST notation, the script
should handle whitespaces and lines with care, as otherwise
the file won't be properly recognized.
Address the bugs that are on such part of the script.
Signed-off-by: Mauro Carvalho Chehab <[email protected]>
---
scripts/get_abi.pl | 30 ++++++++++++++----------------
1 file changed, 14 insertions(+), 16 deletions(-)
diff --git a/scripts/get_abi.pl b/scripts/get_abi.pl
index e2cd2234af34..03f3c57af7ab 100755
--- a/scripts/get_abi.pl
+++ b/scripts/get_abi.pl
@@ -159,7 +159,8 @@ sub parse_abi {
$content = $2;
}
while ($space =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}
- $data{$what}->{$tag} .= $content;
+
+ $data{$what}->{$tag} .= "$content\n" if ($content);
} else {
$data{$what}->{$tag} = $content;
}
@@ -174,31 +175,28 @@ sub parse_abi {
}
if ($tag eq "description") {
+ my $content = $_;
+ while ($content =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}
if (!$data{$what}->{description}) {
- s/^($space)//;
- if (m/^(\s*)(.*)/) {
- my $sp = $1;
- while ($sp =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}
- my $content = "$sp$2";
-
- $content =~ s/^($space)//;
-
- $data{$what}->{$tag} .= "$content";
+ # Preserve initial spaces for the first line
+ if ($content =~ m/^(\s*)(.*)$/) {
+ $space = $1;
+ $content = $2;
}
+
+ $data{$what}->{$tag} .= "$content\n" if ($content);
} else {
- my $content = $_;
if (m/^\s*\n/) {
$data{$what}->{$tag} .= $content;
next;
}
- while ($content =~ s/\t+/' ' x (length($&) * 8 - length($`) % 8)/e) {}
$space = "" if (!($content =~ s/^($space)//));
- # Compress spaces with tabs
- $content =~ s<^ {8}> <\t>;
- $content =~ s<^ {1,7}\t> <\t>;
- $content =~ s< {1,7}\t> <\t>;
+# # Compress spaces with tabs
+# $content =~ s<^ {8}> <\t>;
+# $content =~ s<^ {1,7}\t> <\t>;
+# $content =~ s< {1,7}\t> <\t>;
$data{$what}->{$tag} .= $content;
}
next;
--
2.21.0
Em Fri, 21 Jun 2019 09:32:00 -0300
Mauro Carvalho Chehab <[email protected]> escreveu:
> Hi Greg,
>
> As you proposed to give it a try on removing the escape code from the
> script which parses the ReST file, I changed a few things there,
> adding the capability of selectively enabling to output an ABI sub-dir
> without escaping things that would crash Sphinx.
>
> PS.: As for now this is just a RFC, I'm not getting the ABI file
> maintainers, copying just LKML, linux-doc ML, plus you and Jon.
>
> I also manually fixed the contents of ABI/stable, in order for it to
> pass without causing troubles.
>
> I added all patches from ABI and features at this branch:
>
> https://git.linuxtv.org/mchehab/experimental.git/log/?h=abi_patches_v4.1
>
> The html output is at https://www.infradead.org/~mchehab/rst_features/,
> and you can see the resulting ABI guide on:
>
> https://www.infradead.org/~mchehab/rst_features/admin-guide/abi.html
>
> No Sphinx crashes/warnings happen when building it.
>
> That's my personal notes about such work:
>
> 1) Documentation/ABI/stable/sysfs-class-infiniband
>
> It had some title captions inside it, like:
>
> Errors info:
> -----------
>
> For one of the "What:"
>
> Sphinx is really pick with title markups. As the entire Documentation/stable is
> parsed as if it were a single document, there should be a coherency on what
> character is used to markup a level-one title. I mean, if one document uses:
>
> foo
> ----
>
> For the first level, all other documents should use "---...-" as well.
>
> The alternative would be to have one entry for every single file at
> Documentation/admin-guide/abi-*.rst, with, IMHO, it would be a lot
> harder to maintain.
>
> So, the best seems to let clear at ABI/README about how titles/subtitles
> should be used inside files, if any.
>
> 2) Some documents there use a "Values:" tag, with is not defined as a
> valid one at ABI/README. The script handles it as part of the description,
> so no harm done;
>
> 3) Among the 47 files under ABI/stable, 14 of them names the file
> contents, using a valid ReST markup for the document title. That is shown
> at the index at:
>
> https://www.infradead.org/~mchehab/rst_features/admin-guide/abi.html
>
>
> - ABI stable symbols
>
> - sysfs interface for Mellanox ConnectX HCA IB driver (mlx4)
> - sysfs interface for Intel IB driver qib
> - sysfs interface for Intel(R) X722 iWARP i40iw driver
> - sysfs interface for QLogic qedr NIC Driver
> - sysfs interface for NetEffect RNIC Low-Level iWARP driver (nes)
> - sysfs interface for Cisco VIC (usNIC) Verbs Driver
> - sysfs interface for Chelsio T3 RDMA Driver (cxgb3)
> - sysfs interface for Chelsio T4/T5 RDMA driver (cxgb4)
> - sysfs interface for Intel Omni-Path driver (HFI1)
> - sysfs interface for VMware Paravirtual RDMA driver
> - sysfs interface for Mellanox Connect-IB HCA driver mlx5
> - sysfs interface for Emulex RoCE HCA Driver
> - sysfs interface for Broadcom NetXtreme-E RoCE driver
> - sysfs interface for Mellanox IB HCA low-level driver (mthca)
>
> I liked that, but ideally all ABI files should either use it or not.
>
> 4) I was expecting to have troubles with asterisk characters inside the
> ABI files. That was not the case: I had to escape just one occurrence on
> a single file of the 47 ones inside ABI/stable.
>
> -
>
> My conclusion from this experiment is that it is worth cleaning the ABI
> files for them to be parsed without needing to escape non-ReST compliant
> parts of the ABI file.
>
> Perhaps we could keep rst-compliant the stable, obsolete and removed
> directories only, and gradually moving stuff from ABI/testing to ABI/stable,
> while fixing them to be rst-compliant.
Btw, adding :rst: to kernel-abi markup at abi-obsolete.rst and
abi-removed.rst produced just two warnings:
get_abi.pl rest --dir $srctree/Documentation/ABI/obsolete --rst-source:1689: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/obsolete --rst-source:1692: WARNING: Block quote ends without a blank line; unexpected unindent.
I'll fix those too at my repository.
I suspect, however, that Documentation/ABI/testing with its 353 files will
require a lot more care.
Thanks,
Mauro
diff --git a/Documentation/admin-guide/abi-obsolete.rst b/Documentation/admin-guide/abi-obsolete.rst
index cda9168445a5..d095867899c5 100644
--- a/Documentation/admin-guide/abi-obsolete.rst
+++ b/Documentation/admin-guide/abi-obsolete.rst
@@ -8,3 +8,4 @@ The description of the interface will document the reason why it is
obsolete and when it can be expected to be removed.
.. kernel-abi:: $srctree/Documentation/ABI/obsolete
+ :rst:
diff --git a/Documentation/admin-guide/abi-removed.rst b/Documentation/admin-guide/abi-removed.rst
index 497978fc9632..f7e9e43023c1 100644
--- a/Documentation/admin-guide/abi-removed.rst
+++ b/Documentation/admin-guide/abi-removed.rst
@@ -2,3 +2,4 @@ ABI removed symbols
===================
.. kernel-abi:: $srctree/Documentation/ABI/removed
+ :rst:
Em Fri, 21 Jun 2019 09:39:15 -0300
Mauro Carvalho Chehab <[email protected]> escreveu:
> Em Fri, 21 Jun 2019 09:32:00 -0300
> Mauro Carvalho Chehab <[email protected]> escreveu:
>
> > Hi Greg,
> >
> > As you proposed to give it a try on removing the escape code from the
> > script which parses the ReST file, I changed a few things there,
> > adding the capability of selectively enabling to output an ABI sub-dir
> > without escaping things that would crash Sphinx.
> >
> > PS.: As for now this is just a RFC, I'm not getting the ABI file
> > maintainers, copying just LKML, linux-doc ML, plus you and Jon.
> >
> > I also manually fixed the contents of ABI/stable, in order for it to
> > pass without causing troubles.
> >
> > I added all patches from ABI and features at this branch:
> >
> > https://git.linuxtv.org/mchehab/experimental.git/log/?h=abi_patches_v4.1
> >
> > The html output is at https://www.infradead.org/~mchehab/rst_features/,
> > and you can see the resulting ABI guide on:
> >
> > https://www.infradead.org/~mchehab/rst_features/admin-guide/abi.html
> >
> > No Sphinx crashes/warnings happen when building it.
> >
> > That's my personal notes about such work:
> >
> > 1) Documentation/ABI/stable/sysfs-class-infiniband
> >
> > It had some title captions inside it, like:
> >
> > Errors info:
> > -----------
> >
> > For one of the "What:"
> >
> > Sphinx is really pick with title markups. As the entire Documentation/stable is
> > parsed as if it were a single document, there should be a coherency on what
> > character is used to markup a level-one title. I mean, if one document uses:
> >
> > foo
> > ----
> >
> > For the first level, all other documents should use "---...-" as well.
> >
> > The alternative would be to have one entry for every single file at
> > Documentation/admin-guide/abi-*.rst, with, IMHO, it would be a lot
> > harder to maintain.
> >
> > So, the best seems to let clear at ABI/README about how titles/subtitles
> > should be used inside files, if any.
> >
> > 2) Some documents there use a "Values:" tag, with is not defined as a
> > valid one at ABI/README. The script handles it as part of the description,
> > so no harm done;
> >
> > 3) Among the 47 files under ABI/stable, 14 of them names the file
> > contents, using a valid ReST markup for the document title. That is shown
> > at the index at:
> >
> > https://www.infradead.org/~mchehab/rst_features/admin-guide/abi.html
> >
> >
> > - ABI stable symbols
> >
> > - sysfs interface for Mellanox ConnectX HCA IB driver (mlx4)
> > - sysfs interface for Intel IB driver qib
> > - sysfs interface for Intel(R) X722 iWARP i40iw driver
> > - sysfs interface for QLogic qedr NIC Driver
> > - sysfs interface for NetEffect RNIC Low-Level iWARP driver (nes)
> > - sysfs interface for Cisco VIC (usNIC) Verbs Driver
> > - sysfs interface for Chelsio T3 RDMA Driver (cxgb3)
> > - sysfs interface for Chelsio T4/T5 RDMA driver (cxgb4)
> > - sysfs interface for Intel Omni-Path driver (HFI1)
> > - sysfs interface for VMware Paravirtual RDMA driver
> > - sysfs interface for Mellanox Connect-IB HCA driver mlx5
> > - sysfs interface for Emulex RoCE HCA Driver
> > - sysfs interface for Broadcom NetXtreme-E RoCE driver
> > - sysfs interface for Mellanox IB HCA low-level driver (mthca)
> >
> > I liked that, but ideally all ABI files should either use it or not.
> >
> > 4) I was expecting to have troubles with asterisk characters inside the
> > ABI files. That was not the case: I had to escape just one occurrence on
> > a single file of the 47 ones inside ABI/stable.
> >
> > -
> >
> > My conclusion from this experiment is that it is worth cleaning the ABI
> > files for them to be parsed without needing to escape non-ReST compliant
> > parts of the ABI file.
> >
> > Perhaps we could keep rst-compliant the stable, obsolete and removed
> > directories only, and gradually moving stuff from ABI/testing to ABI/stable,
> > while fixing them to be rst-compliant.
>
> Btw, adding :rst: to kernel-abi markup at abi-obsolete.rst and
> abi-removed.rst produced just two warnings:
>
> get_abi.pl rest --dir $srctree/Documentation/ABI/obsolete --rst-source:1689: ERROR: Unexpected indentation.
> get_abi.pl rest --dir $srctree/Documentation/ABI/obsolete --rst-source:1692: WARNING: Block quote ends without a blank line; unexpected unindent.
>
> I'll fix those too at my repository.
>
> I suspect, however, that Documentation/ABI/testing with its 353 files will
> require a lot more care.
Disabling the escaping logic for ABI/testing won't cause crashes with Sphinx
1.4.9 (it will probably cause more harm on newer versions), but will require
a lot care, as it introduces 248 new errors/warnings:
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:145: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:147: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:148: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:150: WARNING: Definition list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:157: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:158: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:725: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:726: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:888: WARNING: Definition list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:926: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1001: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1106: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1107: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1109: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1110: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1156: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1157: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1162: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1163: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1197: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1198: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1200: WARNING: Definition list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1219: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1307: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1308: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1344: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1345: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1386: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1389: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1399: WARNING: Definition list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1431: WARNING: Definition list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1434: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1476: WARNING: Definition list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1478: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1480: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1513: WARNING: Definition list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1516: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1534: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1535: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1661: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1662: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1690: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1692: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:1906: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:3634: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:3784: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:3785: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:4645: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:4654: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:5358: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:5359: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:5361: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:5362: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:8272: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:8763: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:8951: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:8952: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:8964: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:8975: WARNING: Inline emphasis start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:8981: WARNING: Inline emphasis start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:9247: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:9372: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:9375: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:9399: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:9404: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:9413: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:9415: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:10137: WARNING: Inline emphasis start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:10284: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:10285: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:10691: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:10692: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:10693: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:10702: WARNING: Inline substitution_reference start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:10695: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:10704: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:10824: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:10852: WARNING: Inline substitution_reference start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:10905: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:10918: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:10920: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:12201: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:12203: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:12242: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:12243: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:12292: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:12293: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:12299: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:12300: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:12304: WARNING: Bullet list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:12306: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:12307: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:13006: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:13007: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:13018: WARNING: Bullet list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:13022: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:13023: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:13037: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:13034: WARNING: Inline substitution_reference start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:13038: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:13041: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:13043: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:13050: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:13051: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:13052: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:13053: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:13054: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:13322: WARNING: Definition list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:15110: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:17126: WARNING: Definition list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:17128: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:18028: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:18029: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:18145: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:18146: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:18612: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:18613: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:18826: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:21603: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:21605: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:21607: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:22443: WARNING: Definition list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:23675: WARNING: Inline emphasis start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:24253: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:24254: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:24288: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:24289: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:24290: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:25697: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:25982: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:26095: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:26189: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:26265: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:26303: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:26341: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:26359: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:26535: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:26709: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:26730: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:26855: WARNING: Definition list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:26874: WARNING: Definition list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:26876: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:27863: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:27864: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:27953: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:27954: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:29105: WARNING: Inline emphasis start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:30263: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:31937: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:31941: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:31977: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:31981: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32005: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32007: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32031: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32054: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32058: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32108: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32110: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32136: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32158: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32160: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32204: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32206: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32231: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32254: WARNING: Definition list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32276: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32280: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32306: WARNING: Definition list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32330: WARNING: Definition list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32393: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32394: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32400: WARNING: Definition list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32498: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32518: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32668: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32660: WARNING: Inline substitution_reference start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32660: WARNING: Inline interpreted text or phrase reference start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32660: WARNING: Inline interpreted text or phrase reference start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32698: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32699: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32771: WARNING: Bullet list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32774: WARNING: Bullet list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32902: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:32903: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:33035: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:33038: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:33043: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:33043: WARNING: Inline interpreted text or phrase reference start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:33044: WARNING: Line block ends without a blank line.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:33044: WARNING: Inline interpreted text or phrase reference start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:33045: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:33478: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:34128: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:34132: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:34208: WARNING: Inline interpreted text or phrase reference start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:34386: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:34811: WARNING: Bullet list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:34815: WARNING: Bullet list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:34819: WARNING: Bullet list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:34822: WARNING: Bullet list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:34825: WARNING: Bullet list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:34828: WARNING: Bullet list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:34831: WARNING: Bullet list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:34834: WARNING: Bullet list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:34988: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:35182: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:35538: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:35820: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:35821: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:36003: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:36005: WARNING: Bullet list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:36005: WARNING: Inline emphasis start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:36006: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:36006: WARNING: Inline emphasis start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:36546: WARNING: Inline emphasis start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:36741: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:36745: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:36746: WARNING: Definition list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:37206: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:38654: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:38657: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:38658: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:38712: WARNING: Inline substitution_reference start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:38712: WARNING: Inline substitution_reference start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:38712: WARNING: Inline substitution_reference start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:38712: WARNING: Inline substitution_reference start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:38712: WARNING: Inline substitution_reference start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:38712: WARNING: Inline substitution_reference start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:38712: WARNING: Inline substitution_reference start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:38712: WARNING: Inline substitution_reference start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:38712: WARNING: Inline substitution_reference start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:38787: WARNING: Inline emphasis start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:39407: WARNING: Title underline too short.
Example:
-------
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:39407: WARNING: Title underline too short.
Example:
-------
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:39902: WARNING: Definition list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:41503: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:41505: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:41574: WARNING: Definition list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:41579: WARNING: Block quote ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:41581: WARNING: Definition list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:41586: WARNING: Definition list ends without a blank line; unexpected unindent.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:41588: ERROR: Unexpected indentation.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:45165: WARNING: Inline emphasis start-string without end-string.
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:10695: ERROR: Undefined substitution referenced: "- / | | | |_/ | | | | | | | | irq".
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:3733: ERROR: Unknown target name: "synth_arg".
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:27492: ERROR: Unknown target name: "ptp_pf".
get_abi.pl rest --dir $srctree/Documentation/ABI/testing --rst-source:36117: ERROR: Unknown target name: "entry".
Thanks,
Mauro
Em Fri, 21 Jun 2019 10:04:41 -0300
Mauro Carvalho Chehab <[email protected]> escreveu:
> Em Fri, 21 Jun 2019 09:39:15 -0300
> Mauro Carvalho Chehab <[email protected]> escreveu:
>
> > Em Fri, 21 Jun 2019 09:32:00 -0300
> > Mauro Carvalho Chehab <[email protected]> escreveu:
> >
> > > Hi Greg,
> > >
> > > As you proposed to give it a try on removing the escape code from the
> > > script which parses the ReST file, I changed a few things there,
> > > adding the capability of selectively enabling to output an ABI sub-dir
> > > without escaping things that would crash Sphinx.
> > >
> > > PS.: As for now this is just a RFC, I'm not getting the ABI file
> > > maintainers, copying just LKML, linux-doc ML, plus you and Jon.
> > >
> > > I also manually fixed the contents of ABI/stable, in order for it to
> > > pass without causing troubles.
> > >
> > > I added all patches from ABI and features at this branch:
> > >
> > > https://git.linuxtv.org/mchehab/experimental.git/log/?h=abi_patches_v4.1
> > >
> > > The html output is at https://www.infradead.org/~mchehab/rst_features/,
> > > and you can see the resulting ABI guide on:
> > >
> > > https://www.infradead.org/~mchehab/rst_features/admin-guide/abi.html
> > >
> > > No Sphinx crashes/warnings happen when building it.
> > >
> > > That's my personal notes about such work:
> > >
> > > 1) Documentation/ABI/stable/sysfs-class-infiniband
> > >
> > > It had some title captions inside it, like:
> > >
> > > Errors info:
> > > -----------
> > >
> > > For one of the "What:"
> > >
> > > Sphinx is really pick with title markups. As the entire Documentation/stable is
> > > parsed as if it were a single document, there should be a coherency on what
> > > character is used to markup a level-one title. I mean, if one document uses:
> > >
> > > foo
> > > ----
> > >
> > > For the first level, all other documents should use "---...-" as well.
> > >
> > > The alternative would be to have one entry for every single file at
> > > Documentation/admin-guide/abi-*.rst, with, IMHO, it would be a lot
> > > harder to maintain.
> > >
> > > So, the best seems to let clear at ABI/README about how titles/subtitles
> > > should be used inside files, if any.
> > >
> > > 2) Some documents there use a "Values:" tag, with is not defined as a
> > > valid one at ABI/README. The script handles it as part of the description,
> > > so no harm done;
> > >
> > > 3) Among the 47 files under ABI/stable, 14 of them names the file
> > > contents, using a valid ReST markup for the document title. That is shown
> > > at the index at:
> > >
> > > https://www.infradead.org/~mchehab/rst_features/admin-guide/abi.html
> > >
> > >
> > > - ABI stable symbols
> > >
> > > - sysfs interface for Mellanox ConnectX HCA IB driver (mlx4)
> > > - sysfs interface for Intel IB driver qib
> > > - sysfs interface for Intel(R) X722 iWARP i40iw driver
> > > - sysfs interface for QLogic qedr NIC Driver
> > > - sysfs interface for NetEffect RNIC Low-Level iWARP driver (nes)
> > > - sysfs interface for Cisco VIC (usNIC) Verbs Driver
> > > - sysfs interface for Chelsio T3 RDMA Driver (cxgb3)
> > > - sysfs interface for Chelsio T4/T5 RDMA driver (cxgb4)
> > > - sysfs interface for Intel Omni-Path driver (HFI1)
> > > - sysfs interface for VMware Paravirtual RDMA driver
> > > - sysfs interface for Mellanox Connect-IB HCA driver mlx5
> > > - sysfs interface for Emulex RoCE HCA Driver
> > > - sysfs interface for Broadcom NetXtreme-E RoCE driver
> > > - sysfs interface for Mellanox IB HCA low-level driver (mthca)
> > >
> > > I liked that, but ideally all ABI files should either use it or not.
> > >
> > > 4) I was expecting to have troubles with asterisk characters inside the
> > > ABI files. That was not the case: I had to escape just one occurrence on
> > > a single file of the 47 ones inside ABI/stable.
> > >
> > > -
> > >
> > > My conclusion from this experiment is that it is worth cleaning the ABI
> > > files for them to be parsed without needing to escape non-ReST compliant
> > > parts of the ABI file.
> > >
> > > Perhaps we could keep rst-compliant the stable, obsolete and removed
> > > directories only, and gradually moving stuff from ABI/testing to ABI/stable,
> > > while fixing them to be rst-compliant.
> >
> > Btw, adding :rst: to kernel-abi markup at abi-obsolete.rst and
> > abi-removed.rst produced just two warnings:
> >
> > get_abi.pl rest --dir $srctree/Documentation/ABI/obsolete --rst-source:1689: ERROR: Unexpected indentation.
> > get_abi.pl rest --dir $srctree/Documentation/ABI/obsolete --rst-source:1692: WARNING: Block quote ends without a blank line; unexpected unindent.
> >
> > I'll fix those too at my repository.
> >
> > I suspect, however, that Documentation/ABI/testing with its 353 files will
> > require a lot more care.
>
> Disabling the escaping logic for ABI/testing won't cause crashes with Sphinx
> 1.4.9 (it will probably cause more harm on newer versions), but will require
> a lot care, as it introduces 248 new errors/warnings:
And they come from 71 different files (list enclosed). I didn't look on them,
and I'll stop handling here for now, as I need to handle some other stuff.
Yet, manually fixing those 71 ABI files doesn't sound a too hard work. It
can probably be done on a single day.
So, I suspect we could enable :rst: and manually fix those.
Regards,
Mauro
-
Files that have issues when assuming that they're ReST friendly:
configfs-spear-pcie-gadget
configfs-usb-gadget
configfs-usb-gadget-hid
configfs-usb-gadget-rndis
configfs-usb-gadget-uac1
configfs-usb-gadget-uvc
debugfs-ec
debugfs-pktcdvd
dev-kmsg
evm
ima_policy
procfs-diskstats
sysfs-block
sysfs-block-device
sysfs-bus-acpi
sysfs-bus-event_source-devices-format
sysfs-bus-i2c-devices-pca954x
sysfs-bus-iio
sysfs-bus-iio-adc-envelope-detector
sysfs-bus-iio-cros-ec
sysfs-bus-iio-dfsdm-adc-stm32
sysfs-bus-iio-lptimer-stm32
sysfs-bus-iio-magnetometer-hmc5843
sysfs-bus-iio-temperature-max31856
sysfs-bus-iio-timer-stm32
sysfs-bus-intel_th-devices-msc
sysfs-bus-rapidio
sysfs-bus-thunderbolt
sysfs-bus-usb
sysfs-bus-usb-devices-usbsevseg
sysfs-bus-vfio-mdev
sysfs-class-cxl
sysfs-class-led
sysfs-class-mic.txt
sysfs-class-ocxl
sysfs-class-power
sysfs-class-power-twl4030
sysfs-class-rc
sysfs-class-scsi_host
sysfs-class-typec
sysfs-devices-platform-ACPI-TAD
sysfs-devices-platform-docg3
sysfs-devices-platform-sh_mobile_lcdc_fb
sysfs-devices-system-cpu
sysfs-devices-system-ibm-rtl
sysfs-driver-bd9571mwv-regulator
sysfs-driver-genwqe
sysfs-driver-hid-logitech-lg4ff
sysfs-driver-hid-wiimote
sysfs-driver-samsung-laptop
sysfs-driver-toshiba_acpi
sysfs-driver-toshiba_haps
sysfs-driver-wacom
sysfs-firmware-acpi
sysfs-firmware-dmi-entries
sysfs-firmware-gsmi
sysfs-firmware-memmap
sysfs-fs-ext4
sysfs-hypervisor-xen
sysfs-kernel-boot_params
sysfs-kernel-mm-hugepages
sysfs-platform-asus-laptop
sysfs-platform-asus-wmi
sysfs-platform-at91
sysfs-platform-eeepc-laptop
sysfs-platform-ideapad-laptop
sysfs-platform-intel-wmi-thunderbolt
sysfs-platform-sst-atom
sysfs-platform-usbip-vudc
sysfs-ptp
sysfs-uevent
Thanks,
Mauro