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 details)

Uploaded Source

Built Distribution

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

Uploaded Python 3

File details

Details for the file clang-api-doc-0.4.0.tar.gz.

File metadata

  • Download URL: clang-api-doc-0.4.0.tar.gz
  • Upload date:
  • Size: 5.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.1.8 CPython/3.8.11 Linux/5.8.0-1040-azure

File hashes

Hashes for clang-api-doc-0.4.0.tar.gz
Algorithm Hash digest
SHA256 5e04bfac611aeaa7ffd9cb17f8df080d78eae54df573d5acf1dcf364f3e0ef82
MD5 d9a56208631229363965832e77c1e66e
BLAKE2b-256 a0be4da637cf90b02c222fd5fd8238113743072559e5cdf505726bded30f257c

See more details on using hashes here.

File details

Details for the file clang_api_doc-0.4.0-py3-none-any.whl.

File metadata

  • Download URL: clang_api_doc-0.4.0-py3-none-any.whl
  • Upload date:
  • Size: 6.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: poetry/1.1.8 CPython/3.8.11 Linux/5.8.0-1040-azure

File hashes

Hashes for clang_api_doc-0.4.0-py3-none-any.whl
Algorithm Hash digest
SHA256 71e256058d87b7e0fb88a604e6e0737f443e0565fbba6ab1d75a96afad5d4e36
MD5 70a9704e7a6a1fa541f6a25e3be71815
BLAKE2b-256 a125036682a1047afcc3f403d604637672592fb21bbd362ccc89cea195236de1

See more details on using hashes here.

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