https://github.com/gpmueller/clang-api-doc

Generate API documentation for C language dialects using libclang Python
https://github.com/gpmueller/clang-api-doc

api-documentation api-documentation-tool clang libclang-python3

Last synced: 18 days ago
JSON representation

Generate API documentation for C language dialects using libclang Python

• Host: GitHub
• URL: https://github.com/gpmueller/clang-api-doc
• Owner: GPMueller
• License: mit
• Created: 2019-01-12T19:27:55.000Z (almost 6 years ago)
• Default Branch: master
• Last Pushed: 2021-09-14T20:35:07.000Z (over 3 years ago)
• Last Synced: 2024-11-21T20:12:01.056Z (about 1 month ago)
• Topics: api-documentation, api-documentation-tool, clang, libclang-python3
• Language: Python
• Homepage:
• Size: 74.2 KB
• Stars: 2
• Watchers: 2
• Forks: 0
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE

Awesome Lists containing this project

README

        
clang-api-doc

=============================

Generate C API documentation using libclang Python bindings.

For an example see the [documentation](https://clang-api-doc.readthedocs.io).

[![PyPI version](https://badge.fury.io/py/clang-api-doc.svg)](https://badge.fury.io/py/clang-api-doc)

[![CI](https://github.com/GPMueller/clang-api-doc/actions/workflows/ci.yml/badge.svg)](https://github.com/GPMueller/clang-api-doc/actions/workflows/ci.yml)

[![Codacy Badge](https://app.codacy.com/project/badge/Grade/61ce78fd4cbc41c29ec8eace9bdedca5)](https://www.codacy.com/gh/GPMueller/clang-api-doc/dashboard?utm_source=github.com&utm_medium=referral&utm_content=GPMueller/clang-api-doc&utm_campaign=Badge_Grade)

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.

```bash

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.

```bash

clang-api-doc -i 'include/mylib/' -o 'docs/'

```

Python package usage

-----------------------------

```python

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)

```