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 | None

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

hawkmoth_compiler: str | None

The (path to the) default compiler used by the project. This is used to determine the exact options needed to parse the code files by libclang provided the relevant options are enabled in hawkmoth_autoconf.

Notably, it allows hawkmoth to override libclang’s default search path for system headers with those of the specified compiler.

This presumes the compiler supports being called as <compiler> -x <c|c++> -E -Wp,-v /dev/null.

Defaults to clang, which may differ from libclang’s own default includes.

hawkmoth_autoconf: list[str] | None

List of options that control the automatic configuration features of hawkmoth. Currently supported options:

• 'stdinc': override the standard include paths of libclang with those of the specified compiler (see hawkmoth_compiler).

  This is a shortcut to specify -nostdinc -I<dir 1> ... -I<dir n> in hawkmoth_clang with the search directories of the specified compiler.

Defaults to ['stdinc']. Set to None (or []) to disable automatic configuration, falling back to libclang’s defaults.

hawkmoth_clang: list[str]

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_clang_c: list[str]

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

hawkmoth_clang_cpp: list[str]

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

hawkmoth_source_uri: str | None

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