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.

Files for clang-api-doc, version 0.4.0
Filename, size File type Python version Upload date Hashes
Filename, size clang_api_doc-0.4.0-py3-none-any.whl (6.3 kB) File type Wheel Python version py3 Upload date Hashes View
Filename, size clang-api-doc-0.4.0.tar.gz (5.8 kB) File type Source Python version None Upload date Hashes View

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring DigiCert DigiCert EV certificate Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page