path: root/scripts
diff options
authorMauro Carvalho Chehab <>2020-11-02 11:32:15 +0100
committerGreg Kroah-Hartman <>2020-11-02 13:45:37 +0100
commitdaaaf58a2b7fd59951bd090eddee131f26422e20 (patch)
tree181d51b8ff13bc16c0ea36cdb13e29a2d3894101 /scripts
parente186d80e2b85ab3e69de941d069ab9e11018ddf4 (diff)
scripts: Don't let ABI files to create subtitles
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 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 <> Signed-off-by: Mauro Carvalho Chehab <> Link: Signed-off-by: Greg Kroah-Hartman <>
Diffstat (limited to 'scripts')
1 files changed, 6 insertions, 0 deletions
diff --git a/scripts/ b/scripts/
index 2cb592f8eba4..459f169f834c 100755
--- a/scripts/
+++ b/scripts/
@@ -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;