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.


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


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


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')

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.


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


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.


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.


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