Re: [PATCH 12/14] doc-rst: add ABI documentation to the admin-guide book

[Greg Kroah-Hartman <gregkh@linuxfoundation.org>]

On Fri, Jun 14, 2019 at 04:42:20PM +0300, Jani Nikula wrote:
> On Thu, 13 Jun 2019, Mauro Carvalho Chehab <mchehab+samsung@kernel.org> wrote:
> > From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
> >
> > 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?

> 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 :)

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,

greg k-h