Skip to main content

Hawkmoth - Sphinx Autodoc for C

Project description

GitHub tag (latest SemVer) BSD-2-Clause Read the Docs PyPI Downloads

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.

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, their parameters and return values, structs, unions, their members, macros, function-like macros, enums, enumeration constants, typedefs, variables, as well as have generic documentation comments not attached to any symbols.

Documentation

Documentation on how to install and configure Hawkmoth, and write documentation comments, with examples, is available in the doc directory in the source tree, obviously in Sphinx format and using the directive extension. Pre-built documentation showcasing what Hawkmoth can do is available at Read the Docs.

Installation

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:

There are also Docker images jnikula/hawkmoth and jnikula/hawkmoth-latexpdf at Docker Hub.

In Sphinx conf.py, add hawkmoth to extensions, and point cautodoc_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 https://github.com/jnikula/hawkmoth.git

Please file bugs and feature requests as GitHub issues. Contributions are welcome both as GitHub pull requests (preferred) and as emailed patches to the mailing list.

Dependencies

Dependencies and their minimum versions:

  • Python 3.6
  • Sphinx 3
  • Clang library 6
  • Python 3 Bindings for Clang library 6

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

License

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

Contact

IRC channel #hawkmoth on OFTC IRC network.

Mailing list hawkmoth@freelists.org. Subscription information at the list home page.

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.11.0.tar.gz (18.7 kB view hashes)

Uploaded source

Built Distribution

hawkmoth-0.11.0-py3-none-any.whl (17.3 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page