Built-In Extensions

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

hawkmoth.ext.javadoc

This extension converts Javadoc and Doxygen comments to reStructuredText, using the hawkmoth-process-docstring event.

The most commonly used commands are covered, including some inline markup, using either @ or \ command character. The support is not complete, and mainly covers the basic API documentation needs.

Note that this does not change the comment block format, only the contents of the comments. Only the /** ... */ format is supported.

Installation and configuration in conf.py:

extensions.append('hawkmoth.ext.javadoc')

hawkmoth_javadoc_transform: str

Name of the transformation to handle. Defaults to 'javadoc'. Only convert the comment if the transform option matches this name, otherwise do nothing. Usually there’s no need to modify this option.

For example:

conf.py

extensions.append('hawkmoth.ext.javadoc')
hawkmoth_transform_default = 'javadoc'  # Transform everything

hawkmoth_transform_default sets the default for the transform option.

file.c

/**
 * The baznicator.
 *
 * @param foo The Foo parameter.
 * @param bar The Bar parameter.
 * @return 0 on success, non-zero error code on error.
 * @since v0.1
 */
int baz(int foo, int bar);

api.rst

.. c:autofunction:: baz
   :file: file.c

hawkmoth.ext.napoleon

This extension provides a bridge from Hawkmoth to the sphinx.ext.napoleon extension, using the hawkmoth-process-docstring event, to support Napoleon style documentation comments.

Installation and configuration in conf.py:

extensions.append('hawkmoth.ext.napoleon')

hawkmoth_napoleon_transform: str

Name of the transformation to handle. Defaults to 'napoleon'. Only convert the comment if the transform option matches this name, otherwise do nothing. Usually there’s no need to modify this option.

For example:

conf.py

extensions.append('hawkmoth.ext.napoleon')
# Uncomment to transform everything, example below uses :transform: option
# hawkmoth_transform_default = 'napoleon'

file.c

/**
 * The baznicator.
 *
 * Args:
 *     foo: The Foo parameter.
 *     bar: The Bar parameter.
 *
 * Returns:
 *     0 on success, non-zero error code on error.
 */
int baz(int foo, int bar);

api.rst

.. c:autofunction:: baz
   :file: file.c
   :transform: napoleon

hawkmoth.ext.transformations

This extension handles the cautodoc_transformations feature, using the hawkmoth-process-docstring event.

Note

Going forward, it’s recommended to handle transformations using the event directly instead of cautodoc_transformations. This built-in extension provides backward compatibility for the functionality.

For now, this extension is loaded by default, and the installation step below is not strictly necessary. This will change in the future.

Installation and configuration in conf.py:

extensions.append('hawkmoth.ext.transformations')

cautodoc_transformations: dict

Transformation functions for the c:autodoc directive transform option. This is a dictionary that maps names to functions. The names can be used in the directive transform option. The functions are expected to take a (multi-line) comment string as a parameter, and return the transformed string. This can be used to perform custom conversions of the comments, including, but not limited to, Javadoc-style compat conversions.

The special key None, if present, is used to convert everything, unless overridden in the directive transform option. The special value None means no transformation is to be done.

For example, this configuration would transform everything using default_transform function by default, unless overridden in the directive transform option with javadoc or none. The former would use javadoc_transform function, and the latter would bypass transform altogether.

cautodoc_transformations = {
    None: default_transform,
    'javadoc': javadoc_transform,
    'none': None,
}

The example below shows how to use Hawkmoth’s existing compat functions in conf.py.

from hawkmoth.util import doccompat
cautodoc_transformations = {
    'javadoc-basic': doccompat.javadoc,
    'javadoc-liberal': doccompat.javadoc_liberal,
    'kernel-doc': doccompat.kerneldoc,
}