Am 08.06.2016 um 21:49 schrieb Jonathan Corbet <corbet@xxxxxxx>: > So I've finally gotten a chance to make another pass over this stuff. > > Markus, your enthusiasm is great; I'm hoping you'll do great things > helping us to improve the kernel's documentation toolchain. With 7 years DocBook and 8 years reST experience this is my opportunity to give linux something back ;-) > But please, > at this point, let's build on Jani's work and go from there. Things have > waited for long enough while we've gone around on this; I think what we > have is a good starting point. I'am willing to contribute, but take my POV: I have finished all including migration of **all** DocBook to reST, so why should I throw it all away? Pull it from: https://github.com/return42/linux.git linux-doc-reST The kernel-doc HOWTO [1], the Template Book [2] and make books-help are your friends. You will see that all requirements to get productive are well done. Within the next days I will add more features, which has been requested on the ML. [1] https://return42.github.io/sphkerneldoc/books/kernel-doc-HOWTO [2] http://return42.github.io/sphkerneldoc/books/template-book > > On the specifics, Daniel already covered most of it pretty well. > > On Tue, 7 Jun 2016 09:54:21 +0200 > Daniel Vetter <daniel.vetter@xxxxxxxx> wrote: > >> I think next steps would be: >> - rebase flat-table onto Jani's work and relicense under gplv2 > > This I would really like to see. is already done. > >> - look into rewriting kernel-doc in python more as a long-term project > > There is nobody who would like to dump the Perl kernel-doc more than I > would; it wasn't pretty to begin with and hasn't improved over the years. > I, too, had thought about redoing it, but I, too, concluded that it wasn't > the highest of priorities. > > Please do keep this around, we may want it before too long. I have some > sympathy for Daniel's suggestion to look into using LLVM; we could also > maybe stay a little closer to our roots and use the sparse library. But > there might also be value in a Python version that doesn't add more > dependencies to the docs toolchain. We need to think about this, but I > don't think we need to answer it now. nevertheless which kind of implementation is used, the parsers are all exchangeable. There is only the user interface which has to be stable and this is the ".. kernel-doc:" directive. I implemented a python version of the kernel-doc parser with an (python) API, so why should we fiddle with perl and pipes when implementing a ".. kernel-doc:" directive? > >> - start converting docs instead - I really want to start reaping >> benefits of all this work as soon as possible. > > Absolutely. pull above, there are all converted DocBooks are in. > > Along these lines, I don't currently have a strong opinion on the > big-files vs. little-files question. I *do*, however, like the idea of > trying to create one coherent kernel document rather than perpetuation our > current collection of independent book silos. Initially it will certainly > look like the LDP-based books that people used to duct-tape together back > in the 90's, but it should improve over time. Placing all DocBooks in one huge sphinx-project does not scales well and brings to additional dependencies. To solve this problem I use intersphinx and a index-page where all books are referred. Read chapter "Getting started with reST" from [1]. --Markus-- > > Thanks, > > jon -- 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
