Re: Kernel docs: muddying the waters a bit

From: Markus Heiser
Date: Fri May 06 2016 - 07:23:31 EST

Hy Jani,

Am 04.05.2016 um 18:13 schrieb Jani Nikula <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 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.)

Thats all right. Lets talk about the extension infrastructure by example:

First we have to chose a folder where we place all the *sphinx-documentation*
I recommending:


Next we have to chose a folder where reST-extensions should take place, I
would prefer ... or similar:


Lets say, you wan't to get in use of the "flat-table" extension.

Copy (only) the file from my POC extension folder (ignore
other extensions which might be there) ...

Now lets say you are writing on a gpu book, it wold be placed in the folder:


In this gpu-folder you have to place the config file, needed to
setup the sphinx build environment.


In this you have to *register* your folder with the extensions.

<SNIP> --------

import os.path, sys

EXT_PATH = "../extensions" # the path of extension folder relative to the file
sys.path.insert(0, os.path.join(os.path.dirname(__file__), EXT_PATH)))

# now import the "flat-table" extension, it will be self-registering to docutils

import rstFlatTable

<SNIP> --------

Thats all, you can run your sphinx-build command and the flat-tables in your
reST sources should be handled as common tables.


You will find similar parts in your which you have created
with the sphinx-quickstart command. There, you will also find a block
looks like ...

extensions = [

Don't try to add flat-table extension to this list. This list is a list
of sphinx extensions, we will use it later for other *real* sphinx

A few words about the flat-table extension and a (future) kernel-doc one:

The flat-table is a pure docutils (the layer below sphinx) extension which
is not application specific, so I will ask for moving it to the docutils

The kernel-doc extension on the other side is a very (very) kernel specific
application, this would never go to sphinx nor docutils upstream.