Re: [Ksummit-discuss] [CORE-TOPIC] Documentation

[Daniel Vetter <daniel@ffwll.ch>]

On Tue, Jul 14, 2015 at 10:40 AM, Laurent Pinchart
<laurent.pinchart@ideasonboard.com> wrote:
> (CC'ing Daniel Vetter)
>
> On Monday 13 July 2015 20:36:47 Jonathan Corbet wrote:
>> On Mon, 13 Jul 2015 21:46:46 +0200 Peter Hüwe wrote:
>> > > kerneldoc does work, after a fashion.  It works well enough that people
>> > > use it, and I hear about it quickly when somebody's comment change
>> > > breaks the docs build.  I don't think we can remove it in the absence of
>> > > something better.
>> >
>> > Jonathan, do you keep an up-to-date copy of the generated files somewhere?
>> > (I cannot get it to work out of the box on my machine)
>>
>> I don't, sorry.  That would probably be a good thing for me to do for a
>> number of reasons.
>>
>> > > Creating "something better" is actually on my list of things to do.  The
>> > > only problem is that I've had to buy a second 4TB drive to hold that
>> > > list, so I don't know when I'll have time to think about it.
>> >
>> > Where do you think are the major issues from your point of view?
>>
>> Well, as mentioned before, kerneldoc is fragile.  A little while back
>> somebody changed a struct to a union without updating the comments to
>> match; that was enough to break the entire document build process.  That
>> kind of thing happens a lot; I don't think it should have to be that way.
>>
>> Beyond that, DocBook is a major pain.  I get a fair number of patches
>> along the lines of "that </para> should really have been ahead of that
>> </whatever>".  It's verbose, intimidating to newcomers, and causes more
>> worn-out shift keys than anything else.  We don't need something with the
>> complexity of DocBook; something closer to Markdown or ReST would do us
>> just fine and make the documentation much more accessible.
>>
>> But making any such change is a big job, and convincing the community to
>> go with a change in tooling is probably a bigger job.  So I'm not rushing
>> into it.
>>
>> > Would doxygen be "something better"? The kernel-doc style looks already
>> > quite similar. Maybe the kernel should not reinvent everything :)
>>
>> Doxygen may be worth a look.  I'm personally fond of Sphinx, though I
>> still haven't done a big project in it.
>>
>> But this is all just dreaming until somebody has the time to do a major
>> docs overhaul and sell it to everybody else.  Until then, I'm focused on
>> slowly improving what we have now...
>
> Daniel, I think I recall you mentioning some efforts going in that direction.
> Any update ?

We're contracting collabora (Daniel is working on it, cc'ed) to pimp
the kerneldoc toolchain for us:
- hyperlink functions/structures in the generated docbook
- add markdown support for kerneldoc paragraphs so that you can do
lists, basic formatting and tables

That's the basics I really need, whith that we can probably move all
the text sections from the drm docbook into the code. On top of that
there's a few wishlist items:
- allow to split up per-member sections for long structs (especially
useful for vtable structs where you want some longer text per each
function)
- asciiart or something (box model of drm planes/crtcs isn't the simplest thing)

We do use other stuff in userspace which is orders of magnitude better
than kerneldoc, but kerneldoc+docbook template has intertia. At least
in drm-land, and that's why I decided it's better to stick with it.

My longer-term goal is to fully document drm and i915 internals using
this, to help us bring new engineers up to speed faster. We have a
massive problem with training in that area in drm/i915. I'm also
trying to get a dedicated tech writer to keep all the drm docs written
by various people consistent. Plan is to do that once the kerneldoc
tooling is in more useful shape.
-Daniel
-- 
Daniel Vetter
Software Engineer, Intel Corporation
+41 (0) 79 365 57 48 - http://blog.ffwll.ch