hawkmoth 0.2

Hawkmoth - Sphinx Autodoc for C

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

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

Larval Stage

Hawkmoth is a project very much in its infancy. The main idea is clear, the rough implementation is there and mostly working, even documentation is starting to shape up, but there are bugs, testing is inadequate, there are no promises about backwards compatible changes, it’s not packaged, etc. But it’s usable if you’re not afraid to try software that might be a bit rough around the edges.

Example

Given C source code with rather familiar looking documentation comments:

/**
 * Get foo out of bar.
 */
void foobar();

and a directive in the Sphinx project:

.. c:autodoc:: filename.c

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

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

reStructuredText style field lists are the native way of documenting function parameters and return values and so on, but there’s limited compatibility with Javadoc or Doxygen style @tags.

Documentation

More documentation, with examples, is available in the doc directory in the source tree, obviously in Sphinx format and using the directive extension. Pre-built documentation is available at Read the Docs.

Download

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

git clone https://github.com/jnikula/hawkmoth.git

Dependencies

• Python 3.4

• Sphinx 1.8

• Clang 6.0

• Python 3 Bindings for Clang 6.0

These are the versions Hawkmoth is currently being developed and tested against. Other versions might work, but no guarantees.

Installation

In Sphinx conf.py, point sys.path at Hawkmoth, add hawkmoth to extensions, and point cautodoc_root at the source tree.

You may need to set LD_LIBRARY_PATH so that the Clang library can be found. For example:

export LD_LIBRARY_PATH=$(llvm-config --libdir)

(Did I say the project is in its early stages?)

License

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

Contact

IRC channel #hawkmoth on freenode.

Mailing list [e-mail]. Subscription information at the list home page.