This summer Intel sponsored some work to improve the kerneldoc toolchain, with the aim to use all that to extend the DRM and i915 driver documentation we have. Most of it landed, but the last bit to integrate some type of text markup processing was stalled until it could be discussed at the kernel summit, see the LWN summary. Unfortunately it died in a bikeshed fest due to an alliance of people who think docs are useless and you should just read the code, and others who didn’t even know how to convert the kerneldoc into something pretty.
But we still need this, since without lists, highlighting, basic tables and
inserting code snippets it’s really hard to write decent documentation. Luckily
Dave Airlie is ok with using it for DRM kerneldoc as long as Intel maintains the
support. It’s purely opt-in and the only downside of not using
asciidoc is that the resulting docs won’t be as pretty. All the
changes to the text itself to use this markup are going into upstream as normal.
The only bit that’s not in upstream is the tooling, which is available in a
topic branch at
If you want to build pretty docs just install
asciidoc and base
your drm documentation patches on top of drm-intel-nightly from the same
repository - that tree also includes all of Dave’s tree. Alternatively pull in
the above topic branch into your own personal tree. Note that
asciidoc is detected automatically, so you really only need it and
the tooling branch to check the rendering of your changes.
For added convenience Intel also maintains an autobuilder that pushes latest drm-intel-nightly DRM documentation builds to http://dri.freedesktop.org/docs/drm/.
Aside: If all you want to build is just build the GPU DocBook instead of all of them, you can do that with
$ make DOCBOOKS="gpu.xml" htmldocs
With that have fun reading the new&improved documentation, and if you spot anything please submit a patch to email@example.com.