Re: [PATCH 0/7] add reST/sphinx-doc to linux documentation

[Markus Heiser]

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