Skip to main content

Automatically generate API documentation for C language dialects

Project description

clang-api-doc

Generate C API documentation using libclang Python bindings.

For an example see the documentation.

PyPI version CI Codacy Badge

Why?

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

Installation

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/first.md'
clang-api-doc -i 'include/mylib/second.h' -o 'docs/second.md'

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)

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

clang-api-doc-0.4.0.tar.gz (5.8 kB view hashes)

Uploaded Source

Built Distribution

clang_api_doc-0.4.0-py3-none-any.whl (6.3 kB view hashes)

Uploaded Python 3

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