scripts: get_abi.pl: Don't let ABI files to create subtitles
authorMauro Carvalho Chehab <mchehab+huawei@kernel.org>
Mon, 2 Nov 2020 10:32:15 +0000 (11:32 +0100)
committerGreg Kroah-Hartman <gregkh@linuxfoundation.org>
Mon, 2 Nov 2020 12:45:37 +0000 (13:45 +0100)
commitdaaaf58a2b7fd59951bd090eddee131f26422e20
tree181d51b8ff13bc16c0ea36cdb13e29a2d3894101
parente186d80e2b85ab3e69de941d069ab9e11018ddf4
scripts: get_abi.pl: 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 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>
Link: https://lore.kernel.org/r/6c62ef5c01d39dee8d891f8390c816d2a889670a.1604312590.git.mchehab+huawei@kernel.org
Signed-off-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
scripts/get_abi.pl