From a7a6d70bca68e87ce8d905e67995ee28aaa67f1f Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Tue, 16 Sep 2025 16:47:57 -0700 Subject: [PATCH 1/8] Add script to generate API reference docs with Doxygen --- .gitignore | 3 +++ Doxyfile | 39 ++++++++++++++++++++++++++++++++++++ Makefile | 4 ++++ README.md | 26 ++++++++++++++++++++++++ docs/doxygen-extra.css | 5 +++++ scripts/generate_api_docs.sh | 18 +++++++++++++++++ 6 files changed, 95 insertions(+) create mode 100644 Doxyfile create mode 100644 docs/doxygen-extra.css create mode 100755 scripts/generate_api_docs.sh diff --git a/.gitignore b/.gitignore index 9ef3689..27dc8e5 100644 --- a/.gitignore +++ b/.gitignore @@ -10,6 +10,9 @@ CMakeOutput.log CMakeError.log CMakeLists.txt.user +# Doxygen docs +/docs/_build + .vscode # Mac OS X files .DS_Store diff --git a/Doxyfile b/Doxyfile new file mode 100644 index 0000000..818445f --- /dev/null +++ b/Doxyfile @@ -0,0 +1,39 @@ +PROJECT_NAME = "c2pa-c" +PROJECT_BRIEF = "C API for the C2PA library" +OUTPUT_DIRECTORY = 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..fd5286b 100644 --- a/README.md +++ b/README.md @@ -6,12 +6,14 @@ 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 @@ -75,6 +77,30 @@ Build the [unit tests](https://github.com/contentauth/c2pa-c/tree/main/tests) by make unit-test ``` +## API documentation + +Generate API docs using Doxygen. + +- 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 +``` + +Generate docs: +``` +make -C docs +``` + +Open `build/html/index.html` + + + ## 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..59bc085 --- /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="docs/_build/html" +rm -rf "docs/_build" || true + +doxygen Doxyfile | cat + +echo "Doxygen HTML docs: $OUT_DIR/index.html" + From d26701af0e684fad0e647411caed9ebd17360b4d Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Tue, 16 Sep 2025 16:51:53 -0700 Subject: [PATCH 2/8] Minor README edits --- README.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index fd5286b..8821517 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,7 @@ For the best experience, read the docs on the [CAI Open Source SDK documentation -## 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): @@ -39,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. @@ -99,8 +97,6 @@ make -C docs Open `build/html/index.html` - - ## 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). From f86f319b7ebd2503161f714ac26c30ce69016b87 Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Thu, 18 Sep 2025 13:27:25 -0700 Subject: [PATCH 3/8] Change generated api doc directory to api-docs --- .gitignore | 2 +- Doxyfile | 3 +-- README.md | 2 +- scripts/generate_api_docs.sh | 4 ++-- 4 files changed, 5 insertions(+), 6 deletions(-) diff --git a/.gitignore b/.gitignore index 27dc8e5..f53d597 100644 --- a/.gitignore +++ b/.gitignore @@ -11,7 +11,7 @@ CMakeError.log CMakeLists.txt.user # Doxygen docs -/docs/_build +/api-docs/_build .vscode # Mac OS X files diff --git a/Doxyfile b/Doxyfile index 818445f..5955413 100644 --- a/Doxyfile +++ b/Doxyfile @@ -1,6 +1,6 @@ PROJECT_NAME = "c2pa-c" PROJECT_BRIEF = "C API for the C2PA library" -OUTPUT_DIRECTORY = docs/_build +OUTPUT_DIRECTORY = api-docs/_build CREATE_SUBDIRS = YES GENERATE_HTML = YES GENERATE_LATEX = NO @@ -14,7 +14,6 @@ INPUT = include src README.md FILE_PATTERNS = *.h *.hpp *.c RECURSIVE = YES EXCLUDE_SYMLINKS = YES - MARKDOWN_SUPPORT = YES USE_MDFILE_AS_MAINPAGE = README.md diff --git a/README.md b/README.md index 8821517..b990837 100644 --- a/README.md +++ b/README.md @@ -78,7 +78,7 @@ 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` diff --git a/scripts/generate_api_docs.sh b/scripts/generate_api_docs.sh index 59bc085..425e59a 100755 --- a/scripts/generate_api_docs.sh +++ b/scripts/generate_api_docs.sh @@ -9,8 +9,8 @@ if ! command -v doxygen >/dev/null 2>&1; then exit 1 fi -OUT_DIR="docs/_build/html" -rm -rf "docs/_build" || true +OUT_DIR="api-docs/_build/html" +rm -rf "api-docs/_build" || true doxygen Doxyfile | cat From c7e5c468b30eaf75c1e89c6f90b05efa988a6b26 Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Thu, 18 Sep 2025 15:46:10 -0700 Subject: [PATCH 4/8] Add publish workflow --- .github/workflows/publish-docs.yml | 49 ++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) create mode 100644 .github/workflows/publish-docs.yml diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml new file mode 100644 index 0000000..d849b88 --- /dev/null +++ b/.github/workflows/publish-docs.yml @@ -0,0 +1,49 @@ +name: Build and publish docs + +on: + push: + branches: ['main'] + tags: '*' + + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: '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 + + - uses: ./.github/actions/install-dependencies + name: Install dependencies + + - run: pnpm exec nx run-many -t build --projects=tag:lib + + - name: Build docs + run: pnpm ci:docs + + - name: Upload artifact + uses: actions/upload-pages-artifact@v3 + with: + path: 'docs/' + + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 \ No newline at end of file From e2e8ae07653a3e944a0ba9f4f5b77364987223a2 Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Fri, 19 Sep 2025 11:01:57 -0700 Subject: [PATCH 5/8] Change workflow to run on pushes to main only --- .github/workflows/publish-docs.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml index d849b88..94f37ba 100644 --- a/.github/workflows/publish-docs.yml +++ b/.github/workflows/publish-docs.yml @@ -3,7 +3,6 @@ name: Build and publish docs on: push: branches: ['main'] - tags: '*' workflow_dispatch: From 6a0443bb1424479965c135f31eb6c77f219a5d7f Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Fri, 19 Sep 2025 12:32:14 -0700 Subject: [PATCH 6/8] Fix workflow to install deps and run correct doc build script --- .github/workflows/publish-docs.yml | 8 +++----- README.md | 9 ++++++--- 2 files changed, 9 insertions(+), 8 deletions(-) diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml index 94f37ba..c5d0901 100644 --- a/.github/workflows/publish-docs.yml +++ b/.github/workflows/publish-docs.yml @@ -30,13 +30,11 @@ jobs: - name: Setup Pages uses: actions/configure-pages@v5 - - uses: ./.github/actions/install-dependencies - name: Install dependencies - - - run: pnpm exec nx run-many -t build --projects=tag:lib + - name: Install Doxygen + run: sudo apt-get install doxygen - name: Build docs - run: pnpm ci:docs + run: sh ./scripts/generate_api_docs.sh - name: Upload artifact uses: actions/upload-pages-artifact@v3 diff --git a/README.md b/README.md index b990837..8e5d346 100644 --- a/README.md +++ b/README.md @@ -90,12 +90,15 @@ macOS: brew install doxygen Ubuntu/Debian: sudo apt-get install doxygen ``` -Generate docs: +To generate docs, enter the command: + ``` -make -C docs +./scripts/generate_api_docs.sh ``` -Open `build/html/index.html` +Or run `make -C docs`. + +Open `build/html/index.html` to see the results. ## License From 59b1e6c3f54b3961d7e41403f0532cdb51a77d2d Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Fri, 19 Sep 2025 15:40:53 -0700 Subject: [PATCH 7/8] Add push trigger for wf for testing purposes --- .github/workflows/publish-docs.yml | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml index c5d0901..63da2e1 100644 --- a/.github/workflows/publish-docs.yml +++ b/.github/workflows/publish-docs.yml @@ -1,6 +1,13 @@ name: Build and publish docs on: + pull_request: + types: + - opened + - reopened + - synchronize + - labeled + push: branches: ['main'] @@ -12,7 +19,7 @@ permissions: id-token: write concurrency: - group: 'pages' + group: 'github-pages' cancel-in-progress: false jobs: From 10daab6f64c348cd648b210611962145be6ec6ca Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Fri, 19 Sep 2025 15:50:39 -0700 Subject: [PATCH 8/8] Change build path --- .github/workflows/publish-docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml index 63da2e1..947865c 100644 --- a/.github/workflows/publish-docs.yml +++ b/.github/workflows/publish-docs.yml @@ -46,7 +46,7 @@ jobs: - name: Upload artifact uses: actions/upload-pages-artifact@v3 with: - path: 'docs/' + path: 'api-docs/_build/html/' - name: Deploy to GitHub Pages id: deployment