|badge-tag| |badge-license| |badge-ci| |badge-docs| |badge-rtd| |badge-pypi|
.. |badge-tag| image:: https://img.shields.io/github/v/tag/jnikula/hawkmoth
:target: https://github.com/jnikula/hawkmoth/blob/master/CHANGELOG.rst
:alt: GitHub tag (latest SemVer)
.. |badge-license| image:: https://img.shields.io/github/license/jnikula/hawkmoth
:target: https://opensource.org/licenses/BSD-2-Clause
:alt: BSD-2-Clause
.. |badge-ci| image:: https://github.com/jnikula/hawkmoth/actions/workflows/makefile.yml/badge.svg
:target: https://github.com/jnikula/hawkmoth/actions/workflows/makefile.yml
:alt: Makefile CI
.. |badge-docs| image:: https://github.com/jnikula/hawkmoth/actions/workflows/docs.yml/badge.svg
:target: https://github.com/jnikula/hawkmoth/actions/workflows/docs.yml
:alt: Build and Deploy Documentation
.. |badge-rtd| image:: https://img.shields.io/readthedocs/hawkmoth
:target: https://hawkmoth.readthedocs.io/en/latest/
:alt: Read the Docs
.. |badge-pypi| image:: https://img.shields.io/pypi/dm/hawkmoth
:target: https://pypi.org/project/hawkmoth/
:alt: 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.
**Note**
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.
.. _Sphinx: http://www.sphinx-doc.org
.. _C and C++ Domain: http://www.sphinx-doc.org/en/stable/domains.html
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
Example
-------
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.
.. _examples: https://jnikula.github.io/hawkmoth/stable/examples.html
Documentation
-------------
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`_.
.. _latest release: https://jnikula.github.io/hawkmoth/stable/
.. _version currently in development: https://jnikula.github.io/hawkmoth/dev/
.. _Read the Docs: https://hawkmoth.readthedocs.io/
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:
* `Arch Linux`_
In Sphinx ``conf.py``, add ``hawkmoth`` to ``extensions``, and point
``hawkmoth_root`` at the source tree. See the extension documentation for
details.
.. _PyPI: https://pypi.org/project/hawkmoth/
.. _Arch Linux: https://aur.archlinux.org/packages/?K=hawkmoth
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 as GitHub pull requests.
See `CONTRIBUTING.rst`_ for more details.
.. _GitHub: https://github.com/jnikula/hawkmoth
.. _CONTRIBUTING.rst: https://github.com/jnikula/hawkmoth/blob/master/CONTRIBUTING.rst
Dependencies
------------
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`_.
.. _setup.cfg: https://github.com/jnikula/hawkmoth/blob/master/setup.cfg
License
-------
Hawkmoth is free software, released under the `2-Clause BSD License`_.
.. _2-Clause BSD License: https://opensource.org/licenses/BSD-2-Clause
Contact
-------
IRC channel ``#hawkmoth`` on `OFTC IRC network`_. GitHub issues_ and
discussions_.
.. _OFTC IRC network: https://www.oftc.net/
.. _issues: https://github.com/jnikula/hawkmoth/issues
.. _discussions: https://github.com/jnikula/hawkmoth/discussions
Raw data
{
"_id": null,
"home_page": "https://github.com/jnikula/hawkmoth",
"name": "hawkmoth",
"maintainer": null,
"docs_url": null,
"requires_python": "~=3.8",
"maintainer_email": null,
"keywords": "python, sphinx, autodoc, documentation, c",
"author": "Jani Nikula",
"author_email": "jani@nikula.org",
"download_url": "https://files.pythonhosted.org/packages/11/0b/f019c272d1cabc588e9d238250b006ae0227fe3dde1f93d3591ed29f2efd/hawkmoth-0.18.0.tar.gz",
"platform": null,
"description": "\n|badge-tag| |badge-license| |badge-ci| |badge-docs| |badge-rtd| |badge-pypi|\n\n.. |badge-tag| image:: https://img.shields.io/github/v/tag/jnikula/hawkmoth\n\t\t :target: https://github.com/jnikula/hawkmoth/blob/master/CHANGELOG.rst\n\t\t :alt: GitHub tag (latest SemVer)\n\n.. |badge-license| image:: https://img.shields.io/github/license/jnikula/hawkmoth\n\t\t\t :target: https://opensource.org/licenses/BSD-2-Clause\n\t\t\t :alt: BSD-2-Clause\n\n.. |badge-ci| image:: https://github.com/jnikula/hawkmoth/actions/workflows/makefile.yml/badge.svg\n\t\t :target: https://github.com/jnikula/hawkmoth/actions/workflows/makefile.yml\n\t\t :alt: Makefile CI\n\n.. |badge-docs| image:: https://github.com/jnikula/hawkmoth/actions/workflows/docs.yml/badge.svg\n\t\t\t:target: https://github.com/jnikula/hawkmoth/actions/workflows/docs.yml\n\t\t\t:alt: Build and Deploy Documentation\n\n.. |badge-rtd| image:: https://img.shields.io/readthedocs/hawkmoth\n\t\t :target: https://hawkmoth.readthedocs.io/en/latest/\n\t\t :alt: Read the Docs\n\n.. |badge-pypi| image:: https://img.shields.io/pypi/dm/hawkmoth\n\t\t\t:target: https://pypi.org/project/hawkmoth/\n\t\t\t:alt: PyPI Downloads\n\nHawkmoth - Sphinx Autodoc for C\n===============================\n\nHawkmoth is a minimalistic Sphinx_ `C and C++ Domain`_ autodoc directive\nextension to incorporate formatted C and C++ source code comments written in\nreStructuredText_ into Sphinx based documentation. It uses Clang Python Bindings\nfor parsing, and generates C and C++ Domain directives for C and C++ API\ndocumentation, and more. In short, Hawkmoth is Sphinx Autodoc for C/C++.\n\nHawkmoth aims to be a compelling alternative for documenting C and C++ projects\nusing Sphinx, mainly through its simplicity of design, implementation and use.\n\n**Note**\n\n The C++ support is still in early stages of development, and lacks some\n fundamental features such as handling namespaces and documenting C++ specific\n features other than classes.\n\n.. _Sphinx: http://www.sphinx-doc.org\n\n.. _C and C++ Domain: http://www.sphinx-doc.org/en/stable/domains.html\n\n.. _reStructuredText: http://docutils.sourceforge.net/rst.html\n\nExample\n-------\n\nGiven C source code with rather familiar looking documentation comments::\n\n /**\n * Get foo out of bar.\n *\n * :param bar: Name of the bar.\n */\n void foobar(const char *bar);\n\nand a directive in the Sphinx project::\n\n .. c:autofunction:: foobar\n :file: filename.c\n\nyou can incorporate code documentation into Sphinx. It's as simple as that.\n\nYou can document functions, their parameters and return values, structs,\nclasses, unions, their members, macros, function-like macros, enums, enumeration\nconstants, typedefs, variables, as well as have generic documentation comments\nnot attached to any symbols.\n\nSee the documentation `examples`_ section for more, with sample output.\n\n.. _examples: https://jnikula.github.io/hawkmoth/stable/examples.html\n\nDocumentation\n-------------\n\nDocumentation on how to install, configure and use Hawkmoth, as well as write\ndocumentation comments, with examples, is available for both the `latest\nrelease`_ and the `version currently in development`_.\n\nThe same is also hosted at `Read the Docs`_.\n\n.. _latest release: https://jnikula.github.io/hawkmoth/stable/\n\n.. _version currently in development: https://jnikula.github.io/hawkmoth/dev/\n\n.. _Read the Docs: https://hawkmoth.readthedocs.io/\n\nInstallation\n------------\n\nYou can install Hawkmoth from PyPI_ with::\n\n pip install hawkmoth\n\nYou'll additionally need to install Clang and Python 3 bindings for it through\nyour distro's package manager; they are not available via PyPI. For further\ndetails, see the documentation.\n\nAlternatively, installation packages are available for:\n\n* `Arch Linux`_\n\nIn Sphinx ``conf.py``, add ``hawkmoth`` to ``extensions``, and point\n``hawkmoth_root`` at the source tree. See the extension documentation for\ndetails.\n\n.. _PyPI: https://pypi.org/project/hawkmoth/\n\n.. _Arch Linux: https://aur.archlinux.org/packages/?K=hawkmoth\n\nDevelopment and Contributing\n----------------------------\n\nHawkmoth source code is available on GitHub_. The development version can be\nchecked out via ``git`` using this command::\n\n git clone https://github.com/jnikula/hawkmoth.git\n\nPlease file bugs and feature requests as GitHub issues_. Contributions are\nwelcome as GitHub pull requests.\n\nSee `CONTRIBUTING.rst`_ for more details.\n\n.. _GitHub: https://github.com/jnikula/hawkmoth\n\n.. _CONTRIBUTING.rst: https://github.com/jnikula/hawkmoth/blob/master/CONTRIBUTING.rst\n\nDependencies\n------------\n\nDependencies and their minimum versions:\n\n- Python 3.8\n- Sphinx 3\n- Clang library 6\n- Python 3 Bindings for Clang library 6\n\nThere are additional development and testing dependencies recorded in\n`setup.cfg`_.\n\n.. _setup.cfg: https://github.com/jnikula/hawkmoth/blob/master/setup.cfg\n\nLicense\n-------\n\nHawkmoth is free software, released under the `2-Clause BSD License`_.\n\n.. _2-Clause BSD License: https://opensource.org/licenses/BSD-2-Clause\n\nContact\n-------\n\nIRC channel ``#hawkmoth`` on `OFTC IRC network`_. GitHub issues_ and\ndiscussions_.\n\n.. _OFTC IRC network: https://www.oftc.net/\n\n.. _issues: https://github.com/jnikula/hawkmoth/issues\n\n.. _discussions: https://github.com/jnikula/hawkmoth/discussions\n",
"bugtrack_url": null,
"license": "2-Clause BSD",
"summary": "Hawkmoth - Sphinx Autodoc for C",
"version": "0.18.0",
"project_urls": {
"Documentation": "https://jnikula.github.io/hawkmoth/stable/",
"Homepage": "https://github.com/jnikula/hawkmoth"
},
"split_keywords": [
"python",
" sphinx",
" autodoc",
" documentation",
" c"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b99e5c4ba3478aa501058fedfaff5c8d88a907d3c615d043644e3a7b0829d886",
"md5": "122dcedf59a68c7e4c1b018842fb842f",
"sha256": "b43145950112db7ea30c5c1669b402a46b1b2234c253475f17a3801a93271c99"
},
"downloads": -1,
"filename": "hawkmoth-0.18.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "122dcedf59a68c7e4c1b018842fb842f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "~=3.8",
"size": 30974,
"upload_time": "2024-04-14T13:14:32",
"upload_time_iso_8601": "2024-04-14T13:14:32.862431Z",
"url": "https://files.pythonhosted.org/packages/b9/9e/5c4ba3478aa501058fedfaff5c8d88a907d3c615d043644e3a7b0829d886/hawkmoth-0.18.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "110bf019c272d1cabc588e9d238250b006ae0227fe3dde1f93d3591ed29f2efd",
"md5": "64e0e7d3537bcf609b084dd4f360800a",
"sha256": "5ebe08d21914d929e6dfd3db5d019780ce8b2acda0496deac8fb2dd498998e17"
},
"downloads": -1,
"filename": "hawkmoth-0.18.0.tar.gz",
"has_sig": false,
"md5_digest": "64e0e7d3537bcf609b084dd4f360800a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=3.8",
"size": 32459,
"upload_time": "2024-04-14T13:14:34",
"upload_time_iso_8601": "2024-04-14T13:14:34.432054Z",
"url": "https://files.pythonhosted.org/packages/11/0b/f019c272d1cabc588e9d238250b006ae0227fe3dde1f93d3591ed29f2efd/hawkmoth-0.18.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-14 13:14:34",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jnikula",
"github_project": "hawkmoth",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "flake8",
"specs": []
},
{
"name": "pytest",
"specs": []
},
{
"name": "pytest-cov",
"specs": []
},
{
"name": "pytest-xdist",
"specs": []
},
{
"name": "restructuredtext_lint",
"specs": []
},
{
"name": "sphinx",
"specs": []
},
{
"name": "strictyaml",
"specs": []
}
],
"lcname": "hawkmoth"
}
JSON
