Automatically generate API documentation for C language dialects

api, automatic, documentation, api-documentation, api-documentation-tool, clang, libclang-python3
pip install clang-api-doc==0.4.0



Generate C API documentation using libclang Python bindings.

For an example see the documentation.

PyPI version CI Codacy Badge


Ideally, code should be self-documenting. To me that means little to no documentation should be needed in the code itself, as it strongly tends to harm readability if the code already explains itself. The remaining use-cases for documentation are typically

  • API references, in particular assumed usage contracts
  • usage examples
  • installation instructions
  • general introductions

This project focuses on generating API references, as the other use-cases tend to be written separate from the code.

The markdown-files generated by clang-api-doc can be used in any way you wish to create your final documentation, for example

  • mkdocs
  • sphinx
  • transform to a different format using pandoc


The clang-api-doc package is on PyPI, so you can use pip, poetry, or whatever you like to install it, for example pip install clang-api-doc.

To install it locally and in editable mode, simply install poetry and run poetry install and to load the virtual environment run poetry shell.

CLI usage

Simply call clang-api-doc once per file you wish to document, e.g.

clang-api-doc -i 'include/mylib/first.h' -o 'docs/'
clang-api-doc -i 'include/mylib/second.h' -o 'docs/'

or once per folder, e.g.

clang-api-doc -i 'include/mylib/' -o 'docs/'

Python package usage

from clang_api_doc import clang_api_doc

for file_in, file_out in zip(input_files, output_files):
    clang_api_doc.transform_file(file_in, file_out)