man pages from kernel-doc comments

The linuxdoc.manKernelDoc.KernelDocManBuilder produces manual pages in the groff format. It is a man page builder for Sphinx-doc, mainly written to generate manual pages from kernel-doc comments by scanning Sphinx’s master doc-tree for sections marked with a

.. kernel-doc-man:: <declaration-name>.<man-sect no>

directive and build manual pages from those marked sections. Usage:

$ sphinx-build -b kernel-doc-man ...

Since the kernel-doc-man builder is an extension of the common ManualPageBuilder it is also a full replacement, building booth, the common sphinx man-pages from conf.py man-pages and those marked with the .. kernel-doc-man:: directive.

Mostly authors will use this feature in their reST documents in conjunction with the .. kernel-doc:: directive, to create man pages from kernel-doc comments. This could be done, by setting the Manual section number with the :man-sect: kernel-doc option. See: man pages (:man-sect:)

.. kernel-doc::  ./all-in-a-tumble.c
    :functions: user_function
    :man-sect: 1

With this :man-sect: <man-sect no> option, the kernel-doc parser will insert a directive in the reST output:

.. kernel-doc-man:: <declaration-name>.<man-sect no>

The <declaration-name> is the name of the manual page. Therefor the name of the kernel-doc comment is used. Which is the name of the struct, union, enum, typedef or function.

kernel-doc-man Builder

As described above, the kernel-doc-man builder will build all the manuals which are defined in the conf.py man-pages and from all sections marked with the .. kernel-doc-man directive. To place and gzip the man-pages in dist/docs/man use:

$ sphinx-build -b kernel-doc-man docs dist/docs/man
building [kernel-doc-man]: all manpages ...
scan master tree for kernel-doc man-pages ...
writing man pages ... user_function.2 internal_function.2 ...

$ find dist/docs/man -name '*.[0-9]' -exec gzip -nf {} +

To see how it works, jump to the option :man-sect: example.