<commit_before>Hawkmoth
========

Hawkmoth is a minimalistic Sphinx_ `C Domain`_ autodoc directive extension to
incorporate formatted C source code comments into Sphinx based documentation. It
generates C Domain directives automatically for C API documentation, but is not
limited to that.

.. _Sphinx: http://www.sphinx-doc.org

.. _C Domain: http://www.sphinx-doc.org/en/stable/domains.html

Larval Stage
------------

Hawkmoth is a project very much in its infancy. The main goal is pretty clear:
Use Clang Python Bindings to extract reStructuredText_ documentation comments
from source into Sphinx, and keep it simple. The rough concept is there and
functional, but there are bugs, documentation is lacking, testing is inadequate,
there are no promises about backwards compatible changes, it's not packaged,
etc.

.. _reStructuredText: http://docutils.sourceforge.net/rst.html

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 parameters
and return values and so on, but there's limited compatibility with Javadoc_ or
Doxygen_ style ``@tags``.

.. _Javadoc: http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html

.. _Doxygen: http://www.stack.nl/~dimitri/doxygen/

Documentation
-------------

More documentation, with examples, is available in the ``doc`` directory in the<commit_msg>doc: polish README<commit_after>Hawkmoth
========

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.

.. _Sphinx: http://www.sphinx-doc.org

.. _C Domain: http://www.sphinx-doc.org/en/stable/domains.html

.. _reStructuredText: http://docutils.sourceforge.net/rst.html

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``.

.. _Javadoc: http://www.oracle.com/technetwork/java/javase/documentation/index-jsp-135444.html

.. _Doxygen: http://www.stack.nl/~dimitri/doxygen/

Documentation
-------------

More documentation, with examples, is available in the ``doc`` directory in the
{'fraction_non_alphanumeric': 0.08791760864104496, 'fraction_numerical': 0.003014318010550113, 'mean_word_length': 4.184895833333333, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 8, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '440015', 'n_tokens_mistral': 1156, 'n_tokens_neox': 1062, 'n_words': 485}