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.
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
Built Distribution
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
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5e04bfac611aeaa7ffd9cb17f8df080d78eae54df573d5acf1dcf364f3e0ef82 |
|
MD5 | d9a56208631229363965832e77c1e66e |
|
BLAKE2b-256 | a0be4da637cf90b02c222fd5fd8238113743072559e5cdf505726bded30f257c |
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
Algorithm | Hash digest | |
---|---|---|
SHA256 | 71e256058d87b7e0fb88a604e6e0737f443e0565fbba6ab1d75a96afad5d4e36 |
|
MD5 | 70a9704e7a6a1fa541f6a25e3be71815 |
|
BLAKE2b-256 | a125036682a1047afcc3f403d604637672592fb21bbd362ccc89cea195236de1 |