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 thetransform
option of the directives. Defaults toNone
.
- 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 (seehawkmoth_compiler
).This is a shortcut to specify
-nostdinc -I<dir 1> ... -I<dir n>
inhawkmoth_clang
with the search directories of the specified compiler.
Defaults to
['stdinc']
. Set toNone
(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
afterhawkmoth_clang
in the C domain only.
- hawkmoth_clang_cpp: list[str]¶
Arguments to pass to
clang
afterhawkmoth_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}'