Re: Kernel docs: muddying the waters a bit

[Jani Nikula]

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

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

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center