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

Groups > linux.kernel > #1566244

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

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