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

Jonathan Corbet
2017-01-25T00:13:26Z

On Tue, 24 Jan 2017 20:52:40 +0100
Markus Heiser <markus.heiser@darmarit.de> wrote:

> This patch is the initial merge of a pure python implementation
> to parse kernel-doc comments and generate reST from.
>
> It consist mainly of to parts, the parser module (kerneldoc.py) and the
> sphinx-doc extension (rstKernelDoc.py). For the command line, there is
> also a 'scripts/kerneldoc' added.::
>
> scripts/kerneldoc --help
>
> The main two parts are merged 1:1 from
>
> https://github.com/return42/linuxdoc commit 3991d3c
>
> Take this as a starting point, there is a lot of work to do (WIP).
> Since it is merged 1:1, you will also notice it's CodingStyle is (ATM)
> not kernel compliant and it lacks a user doc ('Documentation/doc-guide').
>
> I will send patches for this when the community agreed about
> functionalities. I guess there are a lot of topics we have to agree
> about. E.g. the py-implementation is more strict the perl one. When you
> build doc with the py-module you will see a lot of additional errors and
> warnings compared to the sloppy perl one.

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?

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

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

Thanks,

jon