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_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}'

cautodoc_root: str

Equivalent to hawkmoth_root.

Warning

The cautodoc_root option has been deprecated in favour of the hawkmoth_root option and will be removed in the future.

cautodoc_clang: str

Equivalent to hawkmoth_clang.

Warning

The cautodoc_clang option has been deprecated in favour of the hawkmoth_clang option and will be removed in the future.