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 thetransform
option matches this name, otherwise do nothing. Usually there’s no need to modify this option.
For example:
extensions.append('hawkmoth.ext.javadoc')
hawkmoth_transform_default = 'javadoc' # Transform everything
hawkmoth_transform_default
sets the default for the transform
option.
/**
* 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);
.. 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 thetransform
option matches this name, otherwise do nothing. Usually there’s no need to modify this option.
For example:
extensions.append('hawkmoth.ext.napoleon')
# Uncomment to transform everything, example below uses :transform: option
# hawkmoth_transform_default = 'napoleon'
/**
* 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);
.. 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
directivetransform
option. This is a dictionary that maps names to functions. The names can be used in the directivetransform
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 directivetransform
option. The special valueNone
means no transformation is to be done.For example, this configuration would transform everything using
default_transform
function by default, unless overridden in the directivetransform
option withjavadoc
ornone
. The former would usejavadoc_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, }