Skip to main content

Hawkmoth - Sphinx Autodoc for C

Project description

GitHub tag (latest SemVer) BSD-2-Clause Makefile CI Build and Deploy Documentation Read the Docs PyPI Downloads

Hawkmoth - Sphinx Autodoc for C

Hawkmoth is a minimalistic Sphinx C and C++ Domain autodoc directive extension to incorporate formatted C and C++ source code comments written in reStructuredText into Sphinx based documentation. It uses Clang Python Bindings for parsing, and generates C and C++ Domain directives for C and C++ API documentation, and more. In short, Hawkmoth is Sphinx Autodoc for C/C++.

Hawkmoth aims to be a compelling alternative for documenting C and C++ projects using Sphinx, mainly through its simplicity of design, implementation and use.


The C++ support is still in early stages of development, and lacks some fundamental features such as handling namespaces and documenting C++ specific features other than classes.


Given C source code with rather familiar looking documentation comments:

 * Get foo out of bar.
 * :param bar: Name of the bar.
void foobar(const char *bar);

and a directive in the Sphinx project:

.. c:autofunction:: foobar
   :file: filename.c

you can incorporate code documentation into Sphinx. It’s as simple as that.

You can document functions, their parameters and return values, structs, classes, unions, their members, macros, function-like macros, enums, enumeration constants, typedefs, variables, as well as have generic documentation comments not attached to any symbols.

See the documentation examples section for more, with sample output.


Documentation on how to install, configure and use Hawkmoth, as well as write documentation comments, with examples, is available for both the latest release and the version currently in development.

The same is also hosted at Read the Docs.


You can install Hawkmoth from PyPI with:

pip install hawkmoth

You’ll additionally need to install Clang and Python 3 bindings for it through your distro’s package manager; they are not available via PyPI. For further details, see the documentation.

Alternatively, installation packages are available for:

In Sphinx, add hawkmoth to extensions, and point hawkmoth_root at the source tree. See the extension documentation for details.

Development and Contributing

Hawkmoth source code is available on GitHub. The development version can be checked out via git using this command:

git clone

Please file bugs and feature requests as GitHub issues. Contributions are welcome as GitHub pull requests.

See CONTRIBUTING.rst for more details.


Dependencies and their minimum versions:

  • Python 3.8

  • Sphinx 3

  • Clang library 6

  • Python 3 Bindings for Clang library 6

There are additional development and testing dependencies recorded in setup.cfg.


Hawkmoth is free software, released under the 2-Clause BSD License.


IRC channel #hawkmoth on OFTC IRC network. GitHub issues and discussions.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

hawkmoth-0.18.0.tar.gz (32.5 kB view hashes)

Uploaded Source

Built Distribution

hawkmoth-0.18.0-py3-none-any.whl (31.0 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page