|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.
.. _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 the `developer documentation`_ for details.
.. _GitHub: https://github.com/jnikula/hawkmoth
.. _developer documentation: https://jnikula.github.io/hawkmoth/dev/developer/
Dependencies
------------
Dependencies and their minimum versions:
- Python 3.9
- 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": null,
"name": "hawkmoth",
"maintainer": null,
"docs_url": null,
"requires_python": "~=3.9",
"maintainer_email": null,
"keywords": "autodoc, c, documentation, python, sphinx",
"author": null,
"author_email": "Jani Nikula <jani@nikula.org>",
"download_url": "https://files.pythonhosted.org/packages/e6/1e/86cf62d3464001724ed8b3d35eca4b0bd0b1135e3e682f5cfe6637149b01/hawkmoth-0.19.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.. _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 the `developer documentation`_ for details.\n\n.. _GitHub: https://github.com/jnikula/hawkmoth\n\n.. _developer documentation: https://jnikula.github.io/hawkmoth/dev/developer/\n\nDependencies\n------------\n\nDependencies and their minimum versions:\n\n- Python 3.9\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": "BSD-2-Clause",
"summary": "Hawkmoth - Sphinx Autodoc for C",
"version": "0.19.0",
"project_urls": {
"Documentation": "https://jnikula.github.io/hawkmoth/stable/",
"Homepage": "https://github.com/jnikula/hawkmoth"
},
"split_keywords": [
"autodoc",
" c",
" documentation",
" python",
" sphinx"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "9d699a37ef58947a9aab54e6196ec7d2f9507320886e70802bc90ef75eb0483f",
"md5": "cf98894de06681335c52a0d400f1c5e6",
"sha256": "7eb42a235274ea5ed383af9c2ea4b4a53466152ec8c3af90f145b731d493814f"
},
"downloads": -1,
"filename": "hawkmoth-0.19.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cf98894de06681335c52a0d400f1c5e6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "~=3.9",
"size": 31021,
"upload_time": "2024-10-26T09:13:19",
"upload_time_iso_8601": "2024-10-26T09:13:19.315813Z",
"url": "https://files.pythonhosted.org/packages/9d/69/9a37ef58947a9aab54e6196ec7d2f9507320886e70802bc90ef75eb0483f/hawkmoth-0.19.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e61e86cf62d3464001724ed8b3d35eca4b0bd0b1135e3e682f5cfe6637149b01",
"md5": "9fca6de78febd341d0a7dc75f919d071",
"sha256": "3718d2520fd9ce7b80288b736dcfec2276466d0c492d7cb41cbc822f12caf32a"
},
"downloads": -1,
"filename": "hawkmoth-0.19.0.tar.gz",
"has_sig": false,
"md5_digest": "9fca6de78febd341d0a7dc75f919d071",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "~=3.9",
"size": 24975,
"upload_time": "2024-10-26T09:13:20",
"upload_time_iso_8601": "2024-10-26T09:13:20.986275Z",
"url": "https://files.pythonhosted.org/packages/e6/1e/86cf62d3464001724ed8b3d35eca4b0bd0b1135e3e682f5cfe6637149b01/hawkmoth-0.19.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-26 09:13:20",
"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": "mypy",
"specs": []
},
{
"name": "pytest",
"specs": []
},
{
"name": "pytest-cov",
"specs": []
},
{
"name": "pytest-xdist",
"specs": []
},
{
"name": "restructuredtext_lint",
"specs": []
},
{
"name": "sphinx",
"specs": []
},
{
"name": "strictyaml",
"specs": []
},
{
"name": "types-docutils",
"specs": []
}
],
"lcname": "hawkmoth"
}
JSON
