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
:symbols: 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.
