Autodoc Extension

Hawkmoth provides a Sphinx extension that adds new directives to the Sphinx C and C++ domains to incorporate formatted C and C++ source code comments into a document. Hawkmoth is Sphinx sphinx.ext.autodoc for C/C++.

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

Hawkmoth itself is extensible, and ships with some built-in extensions.

Usage

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

For example:

extensions.append('hawkmoth')

Configuration

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

See also additional configuration options in the built-in extensions.

hawkmoth_root: str

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
hawkmoth_root = os.path.abspath('my/sources/dir')

hawkmoth_transform_default: str

The default transform parameter to be passed to the hawkmoth-process-docstring event. It can be overriden with the transform option of the directives. Defaults to None.

hawkmoth_clang: list

A list of arguments to pass to clang while parsing the source, typically to add directories to include file search path, or to define macros for conditional compilation. No arguments are passed by default.

Example:

hawkmoth_clang = ['-I/path/to/include', '-DHAWKMOTH']

Hawkmoth provides a convenience helper for querying the include path from the compiler, and providing them as -I options:

from hawkmoth.util import compiler

hawkmoth_clang = compiler.get_include_args()

You can also pass in the compiler to use, for example get_include_args('gcc').

hawkmoth_clang_c: list

Arguments to pass to clang after hawkmoth_clang in the C domain only.

hawkmoth_clang_cpp: list

Arguments to pass to clang after hawkmoth_clang in the C++ domain only.

hawkmoth_source_uri: str

A template URI to source code. If set, add links to externally hosted source code for each documented symbol, similar to the Sphinx linkcode extension. Defaults to None.

The template URI will be formatted using str.format(), with the following replacement fields:

{source}

Path to source file relative to hawkmoth_root.

{line}

Line number in source file.

Example:

hawkmoth_source_uri = 'https://example.org/src/{source}#L{line}'