diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml new file mode 100644 index 0000000..947865c --- /dev/null +++ b/.github/workflows/publish-docs.yml @@ -0,0 +1,53 @@ +name: Build and publish docs + +on: + pull_request: + types: + - opened + - reopened + - synchronize + - labeled + + push: + branches: ['main'] + + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: 'github-pages' + cancel-in-progress: false + +jobs: + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + filter: tree:0 + fetch-depth: 0 + + - name: Setup Pages + uses: actions/configure-pages@v5 + + - name: Install Doxygen + run: sudo apt-get install doxygen + + - name: Build docs + run: sh ./scripts/generate_api_docs.sh + + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: 'api-docs/_build/html/' + + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 \ No newline at end of file diff --git a/.gitignore b/.gitignore index 9ef3689..f53d597 100644 --- a/.gitignore +++ b/.gitignore @@ -10,6 +10,9 @@ CMakeOutput.log CMakeError.log CMakeLists.txt.user +# Doxygen docs +/api-docs/_build + .vscode # Mac OS X files .DS_Store diff --git a/Doxyfile b/Doxyfile new file mode 100644 index 0000000..5955413 --- /dev/null +++ b/Doxyfile @@ -0,0 +1,38 @@ +PROJECT_NAME = "c2pa-c" +PROJECT_BRIEF = "C API for the C2PA library" +OUTPUT_DIRECTORY = api-docs/_build +CREATE_SUBDIRS = YES +GENERATE_HTML = YES +GENERATE_LATEX = NO +GENERATE_MAN = NO +GENERATE_XML = YES +ALWAYS_DETAILED_SEC = YES +INLINE_SOURCES = YES +STRIP_CODE_COMMENTS = NO + +INPUT = include src README.md +FILE_PATTERNS = *.h *.hpp *.c +RECURSIVE = YES +EXCLUDE_SYMLINKS = YES +MARKDOWN_SUPPORT = YES +USE_MDFILE_AS_MAINPAGE = README.md + +HTML_OUTPUT = html +HTML_COLORSTYLE_HUE = 209 +GENERATE_TREEVIEW = YES +HTML_EXTRA_STYLESHEET = docs/doxygen-extra.css + +QUIET = NO +WARN_IF_UNDOCUMENTED = NO +EXTRACT_ALL = YES +EXTRACT_PRIVATE = NO +EXTRACT_STATIC = YES +EXTRACT_LOCAL_METHODS = YES + +ENABLE_PREPROCESSING = YES +MACRO_EXPANSION = YES +EXPAND_ONLY_PREDEF = NO +PREDEFINED = DOXYGEN=1 + +STRIP_FROM_PATH = include src + diff --git a/Makefile b/Makefile index 04e674d..961db3a 100644 --- a/Makefile +++ b/Makefile @@ -44,3 +44,7 @@ clean: .PHONY: all debug release cmake test test-release demo training examples clean +# Build C API docs with Doxygen +docs: + ./scripts/generate_api_docs.sh + diff --git a/README.md b/README.md index 33b0080..8e5d346 100644 --- a/README.md +++ b/README.md @@ -6,15 +6,17 @@ The [c2pa-c repository](https://github.com/contentauth/c2pa-c) implements C++ AP Although this library works for plain C applications, the documentation assumes you're using C++, since that's most common for modern applications. +
For the best experience, read the docs on the [CAI Open Source SDK documentation website](https://opensource.contentauthenticity.org/docs/c2pa-c). If you want to view the documentation in GitHub, see: - [Using the C++ library](docs/usage.md) - [Supported formats](https://github.com/contentauth/c2pa-rs/blob/crandmck/reorg-docs/docs/supported-formats.md) +
-## Using c2pa_cpp in Your Application +## Using c2pa_cpp The recommended way to use this library in your own CMake project is with [FetchContent](https://cmake.org/cmake/help/latest/module/FetchContent.html): @@ -37,12 +39,10 @@ This will automatically fetch, build, and link the `c2pa_cpp` library and its de > **Note:** > This project uses pre-built dynamic libraries from the [c2pa-rs](https://github.com/contentauth/c2pa-rs) repository. It should select the correct library for your platform. If your platform is not supported, you can build your own library using the c2pa_rs repo. -### Example Usage +### Example usage See the [`examples/`](examples/) directory for sample applications that demonstrate how to use the library in practice. ---- - ## Development This project has been tested on macOS and should also work on common Linux distributions. @@ -75,6 +75,31 @@ Build the [unit tests](https://github.com/contentauth/c2pa-c/tree/main/tests) by make unit-test ``` +## API documentation + +Generate API docs using Doxygen. +git +- Configuration file: `c2pa-c/Doxyfile` +- Script: `c2pa-c/scripts/generate_api_docs.sh` +- Output directory: `docs/_build/html` + +Install Doxygen if needed: + +``` +macOS: brew install doxygen +Ubuntu/Debian: sudo apt-get install doxygen +``` + +To generate docs, enter the command: + +``` +./scripts/generate_api_docs.sh +``` + +Or run `make -C docs`. + +Open `build/html/index.html` to see the results. + ## License This package is distributed under the terms of both the [MIT license](https://github.com/contentauth/c2pa-c/blob/main/LICENSE-MIT) and the [Apache License (Version 2.0)](https://github.com/contentauth/c2pa-c/blob/main/LICENSE-APACHE). diff --git a/docs/doxygen-extra.css b/docs/doxygen-extra.css new file mode 100644 index 0000000..2a8b6c4 --- /dev/null +++ b/docs/doxygen-extra.css @@ -0,0 +1,5 @@ +/* Custom classes for Doxygen HTML */ +.hide-doxygen { + display: none; +} + diff --git a/scripts/generate_api_docs.sh b/scripts/generate_api_docs.sh new file mode 100755 index 0000000..425e59a --- /dev/null +++ b/scripts/generate_api_docs.sh @@ -0,0 +1,18 @@ +#!/usr/bin/env bash +set -euo pipefail + +ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +cd "$ROOT_DIR" + +if ! command -v doxygen >/dev/null 2>&1; then + echo "Error: doxygen is not installed. Install it via: brew install doxygen (macOS) or apt-get install doxygen (Linux)." >&2 + exit 1 +fi + +OUT_DIR="api-docs/_build/html" +rm -rf "api-docs/_build" || true + +doxygen Doxyfile | cat + +echo "Doxygen HTML docs: $OUT_DIR/index.html" +