Em Fri, 14 Jun 2019 16:06:03 +0200
Greg Kroah-Hartman [off-list ref] escreveu:

On Fri, Jun 14, 2019 at 04:42:20PM +0300, Jani Nikula wrote:

quoted

On Thu, 13 Jun 2019, Mauro Carvalho Chehab [off-list ref] wrote:  

quoted

From: Mauro Carvalho Chehab <redacted>

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@vger.kernel.org
	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

	...

quoted

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