C Autodoc Extension

Hawkmoth provides a Sphinx extension that adds a new directive to the Sphinx C domain to incorporate formatted C source code comments into a document. Hawkmoth is Sphinx sphinx.ext.autodoc for C.

For this to work, the documentation comments must of course be written in correct reStructuredText. See documentation comment syntax for details.

Installation

Add hawkmoth to extensions in conf.py. Note that depending on the packaging and installation directory, this may require adjusting the PYTHONPATH.

Configuration

The extension has a few configuration options that can be set in conf.py:

cautodoc_root

Path to the root of the source files. Defaults to the configuration directory, i.e. the directory containing conf.py.

To use paths relative to the configuration directory, use os.path.abspath(), for example:

import os
cautodoc_root = os.path.abspath('my/sources/dir')
cautodoc_compat

Compatibility option. One of none (default), javadoc-basic, javadoc-liberal, and kernel-doc. This can be used to perform a limited conversion of Javadoc-style tags to reStructuredText.

Warning

The compatibility options and the subset of supported syntax elements are likely to change.

cautodoc_clang

A comma separated list of arguments to pass to clang while parsing the source, typically to define macros for conditional compilation, for example -DHAWKMOTH. No arguments are passed by default.

Directive

This module provides the following new directive:

.. c:autodoc:: filename-pattern [...]

Incorporate documentation comments from the files specified by the space separated list of filename patterns given as arguments. The patterns are interpreted relative to the cautodoc_root configuration option.

The compat option overrides the cautodoc_compat configuration option.

The clang option overrides the cautodoc_clang configuration option.

Examples

The basic usage is:

.. c:autodoc:: interface.h

Several files with compatibility and compiler options:

.. c:autodoc:: api/*.[ch] interface.h
   :compat: javadoc-basic
   :clang: -DHAWKMOTH