Re: Kernel docs: muddying the waters a bit

[Jonathan Corbet]

On Wed, 4 May 2016 13:50:35 -0300
Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxx> wrote:

> Em Wed, 4 May 2016 19:13:21 +0300
> Jani Nikula <jani.nikula@xxxxxxxxx> escreveu:
> > I think we should go for vanilla sphinx at first, to make the setup step
> > as easy as possible for everyone.  
> 
> Vanilla Sphinx doesn't work, as reST markup language is too limited
> to support the docs we have. So, we should either push the needed
> extensions to Sphinx reST or find a way to put it at Kernel tree
> without causing too much pain for the developers, e. g. as something
> that just doing "make htmldoc" would automatically use such extensions
> without needing to actually install the extensions.

It works for everything except the extended media book, right?  Or is there
something I'm missing here?  I am very much interested in having one system
for *all* our docs, but we wouldn't attempt to convert a document can't be
expressed in sphinx.

> > Even if it means still doing that ugly
> > docproc step to call kernel-doc. We can improve from there, and I
> > definitely appreciate your work on making this work with sphinx
> > extensions.  
> 
> I disagree: We should not cause documentation regressions by
> producing incomplete documentation and losing tables because of
> such conversion.

> The quality of the documentation after the change should be *at least*
> equal to the one we current produce, never worse.

Agreed; that's why I think the existing DocBook mechanism should stay in
place until that document will be improved by the change.  But I'd rather
not hold up the entire process for one book, especially since pushing that
process forward can only help in dealing with those final problems.

> > That said, how would it work to include the kernel-doc extension in the
> > kernel source tree? Having things just work if sphinx is installed is
> > preferred over requiring installation of something extra from pypi. (I
> > know this may sound backwards for a lot of projects, but for kernel I'm
> > pretty sure this is how it should be done.)  
> 
> Yeah, using pypi seems an additional undesired step. Aren't there
> any way to make python to use an additional extension at the
> Kernel tree without needing to install it?

Well, sphinx has to come from somewhere too.  But yes, we should be able to
carry extensions in the kernel tree.  But I would still rather upstream it
(to sphinx) if possible, so we're not stuck trying to maintain it across
several sphinx releases.  I don't know how volatile their interfaces are,
but it would be, in any case, the analog of an out-of-tree module...

jon