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

From: Markus Heiser
Date: Wed Jan 25 2017 - 02:38:50 EST

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/ <--> scripts/kerneldoc -rst
2. Documentation/sphinx/ <--> import module Documentation/sphinx/

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!