lkml.org 
[lkml]   [2016]   [May]   [6]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
    /
    SubjectRe: Kernel docs: muddying the waters a bit
    From
    Date
    Hi Jani,

    I forget to mentioning, with a local copy of my kernel-doc script:

    https://github.com/return42/sphkerneldoc/blob/master/scripts/kernel-doc

    You could do reST markup in the source code comments and extract them.

    This might be a interim workaround which helps you not to edit source
    code comments twice.

    -- Markus--



    Am 06.05.2016 um 13:23 schrieb Markus Heiser <markus.heiser@darmarIT.de>:

    >
    > Hy Jani,
    >
    > Am 04.05.2016 um 18:13 schrieb Jani Nikula <jani.nikula@intel.com>:
    >
    >>> Am 04.05.2016 um 17:09 schrieb Jonathan Corbet <corbet@lwn.net>:
    >>>
    >>>> 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.
    >
    > +1
    >
    >> 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:
    >
    > /share/linux/Documentation/sphinx
    >
    > Next we have to chose a folder where reST-extensions should take place, I
    > would prefer ... or similar:
    >
    > /share/linux/Documentation/sphinx/extensions
    >
    > Lets say, you wan't to get in use of the "flat-table" extension.
    >
    > Copy (only) the rstFlatTable.py file from my POC extension folder (ignore
    > other extensions which might be there) ...
    >
    > https://github.com/return42/sphkerneldoc/tree/master/doc/extensions
    >
    > Now lets say you are writing on a gpu book, it wold be placed in the folder:
    >
    > /share/linux/Documentation/sphinx/gpu
    >
    > In this gpu-folder you have to place the conf.py config file, needed to
    > setup the sphinx build environment.
    >
    > /share/linux/Documentation/sphinx/gpu/conf.py
    >
    > In this conf.py you have to *register* your folder with the extensions.
    >
    > <SNIP conf.py> --------
    >
    > import os.path, sys
    >
    > EXT_PATH = "../extensions" # the path of extension folder relative to the conf.py 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 conf.py> --------
    >
    > Thats all, you can run your sphinx-build command and the flat-tables in your
    > reST sources should be handled as common tables.
    >
    > ASIDE:
    >
    > You will find similar parts in your conf.py which you have created
    > with the sphinx-quickstart command. There, you will also find a block
    > looks like ...
    >
    > extensions = [
    > 'sphinx.ext.autodoc'
    > ....
    > ]
    >
    > 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
    > extensions.
    >
    > 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
    > upstream.
    >
    > The kernel-doc extension on the other side is a very (very) kernel specific
    > application, this would never go to sphinx nor docutils upstream.
    >
    > --Markus--
    >

    \
     
     \ /
      Last update: 2016-05-06 14:21    [W:2.820 / U:0.440 seconds]
    ©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site