Re: [RFC PATCH v1 2/6] kernel-doc: replace kernel-doc perl parser with a pure python one (WIP)

[Markus Heiser]

Hi Jon, hi Daniel !

Am 25.01.2017 um 07:37 schrieb Daniel Vetter <daniel@xxxxxxxx>:

>> Again, quick comments...
>> 
>> - I would *much* rather evolve our existing Sphinx extension in the
>>   direction we want it to go than to just replace it wholesale.
>>   Replacement is the wrong approach for a few reasons, including the need
>>   to minimize change and preserve credit for Jani's work.  Can we work on
>>   that basis, please?

Sure. But I fear I haven't understood you right .... last post was:

> Markus, would you consider sending out a new patch set for review?  What I
> would like to do see is something adding the new script for the Sphinx
> toolchain, while leaving the DocBook build unchanged, using the old
> script.  We could then delete it once the last template file has moved
> over. 

talking about DocBook and now I read ...

>>   Ideally at the time of merging, we would be able to build the docs with
>>   *either* kerneldoc.

Now I'am totally confused ... it's no about you, but I do not understand
you clearly ... can you help a conceptual man?

> Seconded, I think renaming the extension string like this is just fairly
> pointless busy-work.

Hi Daniel, please help me, what did you mean with "renaming" the extension
string and "busy-work"?

There is a renaming of module's name but there should no work outside this
patch ... 

> Kernel-doc isn't interacting perfectly with rst, but
> now we already have a sizeable amount of stuff converted and going through
> all that once more needs imo som really clear benefits.

from authors POV nothing has changed.

> I think bug-for-bug compatibility would be much better. Later on we could do
> changes, on a change-by-change basis.

Both sphinx-extensions (the one we have and the one in the series) are
adapter to a "parser backend". 

1. Documentation/sphinx/kerneldoc.py    <--> scripts/kerneldoc -rst
2. Documentation/sphinx/rstKernelDoc.py <--> import module Documentation/sphinx/kernel_doc.py

Maintain two adapters for the two backends is possible. But one adapter
for two complete different backends .. is this what you mean?

>> - I'll have to try it out to see how noisy it is.  I'm not opposed to
>>   stricter checks; indeed, they could be a good thing.  But we might want
>>   to have an option so we can cut back on the noise by default.

As said, I'am willing to go communities way, it seems just a communication
problem (on my side) to understand what this way would be.

I try to sum what I guess ... e.g. to build output as usual with (1.)

  $ make htmldocs

to build with the py-parser and its sphinx-extension (see 2. above)::

  $ USE_PY_PARSER=1 make htmldocs

this should be easy and I can realize it in v2, but is this what you want?

Please give me some more hints / Thanks a lot!

--Markus--