Skip to main content

Hawkmoth - Sphinx Autodoc for C

Project description

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 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. You may also need to set LD_LIBRARY_PATH so that the Clang library can be found. For example:

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

Alternatively, installation packages are available for:

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 emailed patches to the mailing list and as pull requests.

Dependencies

  • Python 3.4

  • Sphinx 1.8

  • Clang 6.0

  • Python 3 Bindings for Clang 6.0

  • sphinx-testing 1.0.0 (for development)

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

License

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

Contact

IRC channel #hawkmoth on freenode.

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.5.tar.gz (14.2 kB view details)

Uploaded Source

Built Distribution

hawkmoth-0.5-py3-none-any.whl (13.0 kB view details)

Uploaded Python 3

File details

Details for the file hawkmoth-0.5.tar.gz.

File metadata

  • Download URL: hawkmoth-0.5.tar.gz
  • Upload date:
  • Size: 14.2 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.22.0 setuptools/45.1.0 requests-toolbelt/0.9.1 tqdm/4.42.0 CPython/3.7.3

File hashes

Hashes for hawkmoth-0.5.tar.gz
Algorithm Hash digest
SHA256 b3f79cc7e7c73c52396f8cc8b607a781c7082fce3cc32a8e6add2809d046facf
MD5 cbc4bc9416fe0791b51ccf4573cb8205
BLAKE2b-256 9f6b69fdc4db5ee50c08628c56d263990ce4b14fd6bc09b4def9dc2ddec1aac2

See more details on using hashes here.

File details

Details for the file hawkmoth-0.5-py3-none-any.whl.

File metadata

  • Download URL: hawkmoth-0.5-py3-none-any.whl
  • Upload date:
  • Size: 13.0 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.1.1 pkginfo/1.5.0.1 requests/2.22.0 setuptools/45.1.0 requests-toolbelt/0.9.1 tqdm/4.42.0 CPython/3.7.3

File hashes

Hashes for hawkmoth-0.5-py3-none-any.whl
Algorithm Hash digest
SHA256 0bf5997ee2de5e7a7e6c4b19bb6a9635904dfdf2b46e3c5c950c080fde951fc1
MD5 afc6f5b351e1436e414f69baf38120d6
BLAKE2b-256 a2ff96f84eaa3852b2ca18a1781e108ad976f0e609628ebe64d21d46222653a9

See more details on using hashes here.

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