Re: Kernel docs: muddying the waters a bit

[Mauro Carvalho Chehab]

Em Wed, 4 May 2016 19:13:21 +0300
Jani Nikula <jani.nikula@xxxxxxxxx> escreveu:

> On Wed, 04 May 2016, Markus Heiser <markus.heiser@xxxxxxxxxxx> wrote:
> > Correct my, if I'am wrong. I'am a bit unfamiliar with DOCPROC in
> > particular with your "MARKDOWNREADY := gpu.xml" process.
> >
> > As I understood, you convert markdown to docbook within the kernel-doc 
> > script using pandoc's executable? ... I don't face this topic. With my 
> > modification of kernel-doc I produced pure reST markup from standardize
> > kernel-doc markup, no intermediate steps or tools required.  
> 
> That pandoc thing is a dead end. Forget about it. I think we've all
> pretty much agreed we should have kernel-doc produce the lightweight
> markup directly since [1].
> 
> [1] http://mid.gmane.org/1453106477-21359-1-git-send-email-jani.nikula@xxxxxxxxx
> 
> > Am 04.05.2016 um 17:09 schrieb Jonathan Corbet <corbet@xxxxxxx>:
> >  
> >> I think all of this makes sense.  It would be really nice to have the
> >> directives in the native sphinx language like that.  I *don't* think we
> >> need to aim for that at the outset; the docproc approach works until we can
> >> properly get rid of it.  What would be *really* nice would be to get
> >> support for the kernel-doc directive into the sphinx upstream.  
> >
> > No need for kernel-doc directive in sphinx upstream, later it will be 
> > an extension which could be installed by a simple command like 
> > "pip install kernel-doc-extensions" or similar.
> >
> > I develop these required extension (and more) within my proof of concept
> > on github ... this takes time ... if I finished all my tests and all is
> > well, I will build the *kernel-doc-extensions* package and deploy it
> > on https://pypi.python.org/pypi from where everyone could install this 
> > with "pip".  
> 
> 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.

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

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

Thanks,
Mauro