Add ability to generate API reference docs with Doxygen

.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

.gitignore

@@ -10,6 +10,9 @@ CMakeOutput.log
 CMakeError.log
 CMakeLists.txt.user
 
+# Doxygen docs
+/api-docs/_build
+
 .vscode
 # Mac OS X files
 .DS_Store

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
+

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
+

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.
 
+<div class="hide-doxygen" >
 <div style={{display: 'none'}}>
 
 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)
 
+</div>
 </div>
 
-## 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).

docs/doxygen-extra.css

@@ -0,0 +1,5 @@
+/* Custom classes for Doxygen HTML */
+.hide-doxygen {
+  display: none;
+}
+

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"
+