Em Fri, 14 Jun 2019 16:06:03 +0200 Greg Kroah-Hartman <gregkh@xxxxxxxxxxxxxxxxxxx> escreveu: > On Fri, Jun 14, 2019 at 04:42:20PM +0300, Jani Nikula wrote: > > On Thu, 13 Jun 2019, Mauro Carvalho Chehab <mchehab+samsung@xxxxxxxxxx> wrote: > > > From: Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx> > > > > > > As we don't want a generic Sphinx extension to execute commands, > > > change the one proposed to Markus to call the abi_book.pl > > > script. > > > > > > Use a script to parse the Documentation/ABI directory and output > > > it at the admin-guide. > > > > We had a legacy kernel-doc perl script so we used that instead of > > rewriting it in python. Just to keep it bug-for-bug compatible with the > > past. That was the only reason. > > > > I see absolutely zero reason to add a new perl monstrosity with a python > > extension to call it. All of this could be better done in python, > > directly. > > > > Please don't complicate the documentation build. I know you know we all > > worked hard to take apart the old DocBook Rube Goldberg machine to > > replace it with Sphinx. Please don't turn the Sphinx build to another > > complicated mess. > > > > My strong preferences are, in this order: > > > > 1) Convert the ABI documentation to reStructuredText > > What would that exactly look like? What would it require for new > developers for when they write new entries? Why not rely on a helper > script, that allows us to validate things better? Funny enough, this e-mail arrived here after Greg's reply, and my reply over his one :-) - With regards to the script, my idea is to have it run on a new "validate" mode, when the Kernel is built with COMPILE_TEST: https://git.linuxtv.org/mchehab/experimental.git/log/?h=abi_patches_v4 NB: the last patch is not yet... somehow, the building system is not passing CONFIG_WARN_ABI_ERRORS to Documentation/Makefile. I'm debugging it. Personally, I would prefer to keep it the way it is, with two additions: 1) I would add a SPDX header at the fist line of each file there; 2) It would make sense to have a new field - or indicator - to let add ReST markups at the description. The advantage of using a parseable ABI file is that it is possible to parse it, for example, to search for a symbol: $ ./scripts/get_abi.pl voltage_max /sys/class/power_supply/<supply_name>/voltage_max ------------------------------------------------- Date: January 2008 Contact: linux-pm@xxxxxxxxxxxxxxx Defined on file: Documentation/ABI/testing/sysfs-class-power Description: Reports the maximum VBUS voltage the supply can support. Access: Read Valid values: Represented in microvolts ... > > > 2) Have the python extension read the ABI files directly, without an > > extra pipeline. > > He who writes the script, get's to dictate the language of the script :) No idea about how much time it would take if written in python, but this perl script is really fast: $ time ./scripts/get_abi.pl search voltage_max >/dev/null real 0m0,139s user 0m0,132s sys 0m0,006s That's the time it takes here (SSD disks) to read all files under Documentation/ABI, parse them and seek for a string. That's about half of the time a python script takes to just import the the sphinx modules and print its version, running at the same machine: $ time sphinx-build --version >/dev/null real 0m0,224s user 0m0,199s sys 0m0,024s > Personally, this looks sane to me, I'm going to apply the ABI fixups to > my tree at least, and then see how the script works out. The script can > always be replaced with a different one in a different language at a > later point in time of people think it really mattes. Thanks, Mauro
