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@xxxxxxxxxxx> 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 -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
