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

Am 04.05.2016 um 11:58 schrieb Jani Nikula <>:

> On Wed, 04 May 2016, Markus Heiser <> wrote:
>> but I think this will not by very helpful, as long as you miss
>> a similar ".tmpl" workflow for reST documents.
>> I'am working on a reST directive (named: "kernel-doc") to provide a
>> similar ".tmpl" workflow within plain reST. The first step towards
>> is done with (my) modified kernel-doc script ...
>> *
>> which produce reST from source code comments. E.g. this content is
>> generated with it.
> What do you mean by ".tmpl workflow"?

Sorry for bad naming, I addressed the DOCPROC build process which builds
the .xml files from .tmpl files ...

<SNIP> ----
# The build process is as follows (targets):
# (xmldocs) [by docproc]
# file.tmpl --> file.xml +--> (psdocs) [by db2ps or xmlto]
# +--> file.pdf (pdfdocs) [by db2pdf or xmlto]
# +--> DIR=file (htmldocs) [by xmlto]
# +--> man/ (mandocs) [by xmlto]
# DOCPROC is used for two purposes:
# 1) To generate a dependency list for a .tmpl file
# 2) To preprocess a .tmpl file and call kernel-doc with
# appropriate parameters.
# The following rules are used to generate the .xml documentation
# required to generate the final targets. (ps, pdf, html).
<SNAP> -----

The DOCPROC markup directives are described in the kernel-doc-nano-HOWTO:

My aim is to implement a reST-directive which is similar. E.g:

<XML-SNIP> -----
<title>Device Instance and Driver Handling</title>
!Pdrivers/gpu/drm/drm_drv.c driver instance overview
<XML-SNAP> -----

In reST the directive might look like:

<reST-SNIP> -----
Device Instance and Driver Handling

.. kernel-doc:: drivers/gpu/drm/drm_drv.c
:doc: driver instance overview

<reST-SNAP> -----

> I'd be *very* hesitant about adding the kind of things you do in
> reformat_block_rst to kernel-doc. IMO the extraction from kernel-doc
> comments must be as simple as possible with basically pass-through of
> the comment blocks to sphinx.

Right, but you forgot, that the current markup in the source code comments
is based on the kernel-doc-nano-HOWTO and I guess no one will migrate all
these source code comments to reST markup ;-)

So there is a need to differentiate between *vintage* kernel-doc markup
and reST markup.

My suggestion is to add a tag to the comments, here a short example
what this might look like.

<vintage-comment-SNIP> --------------
* drm_minor_release - Release DRM minor
* @minor: Pointer to DRM minor object
* Release a minor that was previously acquired via drm_minor_acquire().
<vintage-comment-SNAP> --------------

in short: the vintage style does not need any change and
comments with reST markup has a tag ":reST:" in the first
line(s) ...

<reST-comment-SNIP> --------------
* :reST:
* .. c:function:: void drm_minor_release(struct drm_minor *minor)
* Release DRM minor
* :param struct drm_minor \*minor: Pointer to DRM minor object
<reST-comment-SNAP> --------------

Comments with the ":reST:" tag could be exported and pass-through
to sphinx.

> Specifically, do not attempt to detect and
> parse elements like lists in kernel-doc.

If your markup in the comments is plain reST, no need to parse, but there
are markups in the (vintage) comments which made use of individual
text-markups, e.g. the markup of lists or ASCII-art.

This individual text-markups has not been converted/rendered in the docbook
output, but I wanted to convert this individuals to reST, to render them in

E.g. compare the member & description section of struct drm-display-mode ...



kernel-doc reST with the additional reformat_block_rst function:


-- Markus--

> --
> Jani Nikula, Intel Open Source Technology Center
> --
> To unsubscribe from this list: send the line "unsubscribe linux-media" in
> the body of a message to
> More majordomo info at

 \ /
  Last update: 2016-05-04 15:01    [W:0.196 / U:3.908 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site