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
Hashes for clang_api_doc-0.4.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 71e256058d87b7e0fb88a604e6e0737f443e0565fbba6ab1d75a96afad5d4e36 |
|
MD5 | 70a9704e7a6a1fa541f6a25e3be71815 |
|
BLAKE2b-256 | a125036682a1047afcc3f403d604637672592fb21bbd362ccc89cea195236de1 |