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

[Mauro Carvalho Chehab]

Em Thu, 27 Jun 2019 12:48:12 +0300
Jani Nikula <jani.nikula@xxxxxxxxxxxxxxx> escreveu:

> On Fri, 21 Jun 2019, Mauro Carvalho Chehab <mchehab+samsung@xxxxxxxxxx> wrote:
> > Em Wed, 19 Jun 2019 13:37:39 -0300
> > Mauro Carvalho Chehab <mchehab+samsung@xxxxxxxxxx> escreveu:
> >  
> >> Em Tue, 18 Jun 2019 11:47:32 +0300
> >> Jani Nikula <jani.nikula@xxxxxxxxxxxxxxx> escreveu:
> >>   
> >> > On Mon, 17 Jun 2019, Mauro Carvalho Chehab <mchehab+samsung@xxxxxxxxxx> wrote:    
> >> > > Yeah, I guess it should be possible to do that. How a python script
> >> > > can identify if it was called by Sphinx, or if it was called directly?      
> >> > 
> >> > if __name__ == '__main__':
> >> > 	# run on the command-line, not imported    
> >> 
> >> Ok, when I have some spare time, I may try to convert one script
> >> to python and see how it behaves.   
> >
> > Did a quick test here... 
> >
> > Probably I'm doing something wrong (as I'm a rookie with Python), but,
> > in order to be able to use the same script as command line and as an Sphinx
> > extension, everything that it is currently there should be "escaped"
> > by an:
> >
> > 	if __name__ != '__main__':
> >
> > As event the class definition:
> >
> >     class KernelCmd(Directive):
> >
> > depends on:
> >
> > 	from docutils.parsers.rst import directives, Directive
> >
> > With is only required when one needs to parse ReST - e. g. only
> > when the script runs as a Sphinx extension.
> >
> > If this is right, as we want a script that can run by command line
> > to parse and search inside ABI files, at the end of the day, it will
> > be a lot easier to maintain if the parser script is different from the
> > Sphinx extension.   
> 
> Split it into two files, one has the nuts and bolts of parsing and has
> the "if __name__ == '__main__':" bit to run on the command line, and the
> other interfaces with Sphinx and imports the parser.

It seems we have an agreement here: the best is indeed to have two
files, one with the Documentation/ABI parser, and another one with the 
Sphinx extension...

> 
> > If so, as the Sphinx extension script will need to call a parsing script
> > anyway, it doesn't matter the language of the script with will be
> > doing the ABI file parsing.  
> 
> Calling the parser using an API will be easier to use, maintain and
> extend than using pipes, with all the interleaved sideband information
> to adjust line numbers and whatnot.

... and here is where we have two different views.

From debug PoV, the Documentation/ABI parser script should be able to
print the results by a command line call. This is also a feature
that it is useful for the users: to be able to seek for a symbol
and output its ABI description. So, the "stdout" output will be
there anyway.

The only extra data for the extension side is the file name where
the information came and the line number.

From maintainership PoV, adding the sideband API for file+line is
one line at the parser script (a print) and two lines at the Sphinx
extension (a regex expression and a match line). That's simple to
maintain.

It is also simple to verify both sides independently, as what
you see when running the parser script is what you get at the
extension.

If we add a new ABI between the parser script and the extension
script, this would require to also maintain the ABI, and would
make harder to identify problems on ABI problems.

-

Another advantage of having those independent is that the
language of the parsing script can be different. Not being
python is a big advantage for me, as perl is a lot more
intuitive and easier to write parser scripts for my eyes.

I can write a perl parsing script in a matter of minutes.
It takes me a lot more time to do the same with python, and then
ensure that it will work with two similar but different languages
(python2 and python3) [1].

[1] btw, with that regards, I still don't know how to teach a
    python script that it should "prefer" to run with python3 but would
    fall back to python2. Adding this shebang:
	# /usr/bin/env python
    just do the opposite - at least on Fedora


Thanks,
Mauro