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
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
> 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!