Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > linux.kernel > #1566340

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

Show all headers | View raw

On Tue, Jan 24, 2017 at 05:13:14PM -0700, Jonathan Corbet wrote:
> 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.

Seconded, I think renaming the extension string like this is just fairly
pointless busy-work. 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. I think
bug-for-bug compatibility would be much better. Later on we could do
changes, on a change-by-change basis.
-Daniel


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

-- 
Daniel Vetter
Software Engineer, Intel Corporation
http://blog.ffwll.ch

Back to linux.kernel | Previous | Next — Previous in thread | Next in thread | Find similar | Unroll thread

Thread

[RFC PATCH v1 0/6] pure python kernel-doc parser and more Markus Heiser <markus.heiser@darmarit.de> - 2017-01-24 21:00 +0100
  [RFC PATCH v1 5/6] kernel-doc: add kerneldoc-src2rst command Markus Heiser <markus.heiser@darmarit.de> - 2017-01-24 21:00 +0100
  [RFC PATCH v1 4/6] kernel-doc: insert TODOs on kernel-doc errors Markus Heiser <markus.heiser@darmarit.de> - 2017-01-24 21:00 +0100
  Re: [RFC PATCH v1 2/6] kernel-doc: replace kernel-doc perl parser  with a pure python one (WIP) Jonathan Corbet <corbet@lwn.net> - 2017-01-25 01:20 +0100
    Re: [RFC PATCH v1 2/6] kernel-doc: replace kernel-doc perl parser  with a pure python one (WIP) Daniel Vetter <daniel@ffwll.ch> - 2017-01-25 07:40 +0100
      Re: [RFC PATCH v1 2/6] kernel-doc: replace kernel-doc perl parser with a pure python one (WIP) Markus Heiser <markus.heiser@darmarit.de> - 2017-01-25 08:40 +0100
    Re: [RFC PATCH v1 2/6] kernel-doc: replace kernel-doc perl parser with a pure python one (WIP) Jani Nikula <jani.nikula@intel.com> - 2017-01-25 11:30 +0100
      Re: [RFC PATCH v1 2/6] kernel-doc: replace kernel-doc perl parser  with a pure python one (WIP) Daniel Vetter <daniel@ffwll.ch> - 2017-01-25 11:40 +0100
      Re: [RFC PATCH v1 2/6] kernel-doc: replace kernel-doc perl parser with a pure python one (WIP) Markus Heiser <markus.heiser@darmarit.de> - 2017-01-25 20:10 +0100
        Re: [RFC PATCH v1 2/6] kernel-doc: replace kernel-doc perl parser with a pure python one (WIP) Jani Nikula <jani.nikula@intel.com> - 2017-01-25 22:00 +0100
          Re: [RFC PATCH v1 2/6] kernel-doc: replace kernel-doc perl parser with a pure python one (WIP) Markus Heiser <markus.heiser@darmarit.de> - 2017-01-26 11:00 +0100
            Re: [RFC PATCH v1 2/6] kernel-doc: replace kernel-doc perl parser with a pure python one (WIP) Jani Nikula <jani.nikula@intel.com> - 2017-01-26 11:20 +0100
        Re: [RFC PATCH v1 2/6] kernel-doc: replace kernel-doc perl parser  with a pure python one (WIP) Jonathan Corbet <corbet@lwn.net> - 2017-01-26 20:00 +0100
          Re: [RFC PATCH v1 2/6] kernel-doc: replace kernel-doc perl parser with a pure python one (WIP) Jani Nikula <jani.nikula@intel.com> - 2017-01-26 20:40 +0100
            Re: [RFC PATCH v1 2/6] kernel-doc: replace kernel-doc perl parser with a pure python one (WIP) Markus Heiser <markus.heiser@darmarit.de> - 2017-01-27 10:50 +0100

csiph-web