LinuxDoc Sphinx-doc extensions for sophisticated C developer (NEW, 2016-07)

See also

Introduction

The LinuxDoc library contains sphinx-doc extensions and command line tools to extract documentation from C/C++ source file comments.

Even if this project started in context of the Linux-Kernel documentation, you can use these extensions in common sphinx-doc projects.

LinuxDoc is hosted at github: https://github.com/return42/linuxdoc

LinuxDoc feature overview

kernel-doc

A “C” friendly markup, the parser, the Sphinx-doc extension and some tools. The kernel-doc markup embeds documentation within the C source files, using a few simple conventions. The parser grabs the documentation from source and generates proper reST [ref]. The parser is written in Python and its API is used by the corresponding Sphinx-doc extension. Command line tools shipped with:

  • kernel-autodoc: Suitable for automatic API documentation [ref].
  • kernel-lintdoc: Lint kernel-doc comments from source code [ref].
  • kernel-doc: A command line interface for kernel-doc’s parser API [ref].
kernel-doc-man
A man page builder. An extension/replacement of the common Sphinx-doc man builder also integrated in the kernel-doc Sphinx-doc extension [ref].
flat-table
A diff and author friendly list-table replacement with column-span, row-span and auto-span [ref].
cdomain
A customized Sphinx’s C Domain extension. Suitable for demanding projects [ref].
kfigure
Sphinx extension which implements scalable image handling. Simplifies image handling from the author’s POV. Wins where Sphinx-doc image handling fails. Whatever graphic tools available on your build host, you always get the best output-format. Graphviz’s DOT format included [ref].
kernel-include
A replacement for the include reST directive. The directive expand environment variables in the path name and allows to include files from arbitrary locations ref:[ref] <kernel-include-directive>.

Install LinuxDoc

Install bleeding edge.:

pip install git+http://github.com/return42/linuxdoc.git

As the LinuxDoc lib evolving constantly, an update should be carried out regularly.:

pip install --upgrade git+http://github.com/return42/linuxdoc.git

If you are a developer and like to contribute to the LinuxDoc lib, fork on github or clone and make a developer install:

git clone https://github.com/return42/linuxdoc
cd linuxdoc
make install

Below you see how to integrate the LinuxDoc sphinx extensions into your sphinx build process. In the conf.py (sphinx config) add the LinuxDoc extensions:

extensions = [
  'linuxdoc.rstFlatTable'      # Implementation of the 'flat-table' reST-directive.
  , 'linuxdoc.rstKernelDoc'    # Implementation of the 'kernel-doc' reST-directive.
  , 'linuxdoc.kernel_include'  # Implementation of the 'kernel-include' reST-directive.
  , 'linuxdoc.manKernelDoc'    # Implementation of the 'kernel-doc-man' builder
  , 'linuxdoc.cdomain'         # Replacement for the sphinx c-domain.
  , 'linuxdoc.kfigure'         # Sphinx extension which implements scalable image handling.
]