From cd4fba1864351d979ed0f80a43224f95d260ac2f Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Thu, 5 Nov 2026 15:41:02 -0800 Subject: [PATCH 1/3] docs: update API doc versions on stable releases Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .github/workflows/publish-docs.yml | 24 ++++++++++++++++++++++++ README.md | 1 + docs/project-contributions.md | 11 ++++++++--- 3 files changed, 33 insertions(+), 3 deletions(-) diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml index 523f13ac..1fae6435 100644 --- a/.github/workflows/publish-docs.yml +++ b/.github/workflows/publish-docs.yml @@ -26,6 +26,10 @@ concurrency: jobs: deploy: + permissions: + contents: write + pages: write + id-token: write environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }} @@ -37,6 +41,26 @@ jobs: fetch-depth: 0 ref: main + - name: Add release to versioned documentation + if: github.event_name == 'release' && !github.event.release.prerelease + env: + RELEASE_TAG: ${{ github.event.release.tag_name }} + run: | + if [[ ! "$RELEASE_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then + echo "::error::Stable release tags must use the format vX.Y.Z" + exit 1 + fi + jq --arg tag "$RELEASE_TAG" '.versions = [$tag] + (.versions - [$tag])' \ + api-docs/versions.json > api-docs/versions.json.tmp + mv api-docs/versions.json.tmp api-docs/versions.json + git add api-docs/versions.json + if ! git diff --cached --quiet; then + git config user.name "github-actions[bot]" + git config user.email "41898282+github-actions[bot]@users.noreply.github.com" + git commit -m "docs: add $RELEASE_TAG to the versioned docs" + git push origin HEAD:main + fi + - name: Setup Pages uses: actions/configure-pages@v5 diff --git a/README.md b/README.md index 8ceec28e..908bb331 100644 --- a/README.md +++ b/README.md @@ -102,6 +102,7 @@ API documentation is published at [github.io/c2pa-python/api/c2pa](https://conte Use the documentation version dropdown to choose a published release. The versions are selected in `api-docs/versions.json`; the first entry is the default at the existing documentation URL. +Publishing a stable GitHub release automatically adds its tag as the default while retaining older versions. To build documentation locally, see [Contributing to the project](https://github.com/contentauth/c2pa-python/blob/main/docs/project-contributions.md#api-reference-documentation). diff --git a/docs/project-contributions.md b/docs/project-contributions.md index 48820ba9..45613332 100644 --- a/docs/project-contributions.md +++ b/docs/project-contributions.md @@ -161,7 +161,9 @@ This uses `sphinx-autoapi` to parse `src/c2pa` directly, avoiding imports of nat Edit [api-docs/versions.json](../api-docs/versions.json) to choose the exact GitHub release tags shown in the sidebar dropdown. Entries must be unique tags such as `v0.38.0`. The first entry is the default served at the existing -documentation URL; new releases are not automatically added to the list. +documentation URL. When a stable GitHub release is published, the publishing +workflow prepends its tag and commits the updated list to `main` before building +the site. Older entries are retained; pre-releases are not automatically added. Fetch the release tags and build the complete site: @@ -191,5 +193,8 @@ The complete site is written to `api-docs/_build/versioned/`: The publishing workflow always checks out `main` for the release list and build tooling, including when triggered by a release. It rebuilds all selected versions when a release is published, when relevant documentation files change -on `main`, or when manually dispatched. Publish changes to the list on `main` -to add, remove, or reorder dropdown entries. +on `main`, or when manually dispatched. The workflow needs permission to push +the version-list commit to `main`, including under any branch protection rules. +The same release-triggered run builds and deploys the updated list; it does not +rely on the bot's push triggering another workflow. Publish manual changes to +the list on `main` to add, remove, or reorder dropdown entries. From 1df08ce8153aef6e33c052c05c477e208095c848 Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Mon, 9 Nov 2026 09:18:10 -0800 Subject: [PATCH 2/3] Add .scout to .gitignore --- .gitignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.gitignore b/.gitignore index 9fa3c1eb..98db70ec 100644 --- a/.gitignore +++ b/.gitignore @@ -88,6 +88,7 @@ coverage.xml *.swo *.sublime-project *.sublime-workspace +.scout/ # macOS .DS_Store From 1267dd50512bdcbeda380dd655e366dbfcf9f091 Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Mon, 9 Nov 2026 09:23:47 -0800 Subject: [PATCH 3/3] Update workflow regex to accommodate optional prerelease suffix, e.g. '-alpha' --- .github/workflows/publish-docs.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml index 1fae6435..0a5876c0 100644 --- a/.github/workflows/publish-docs.yml +++ b/.github/workflows/publish-docs.yml @@ -46,8 +46,8 @@ jobs: env: RELEASE_TAG: ${{ github.event.release.tag_name }} run: | - if [[ ! "$RELEASE_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+$ ]]; then - echo "::error::Stable release tags must use the format vX.Y.Z" + if [[ ! "$RELEASE_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?$ ]]; then + echo "::error::Release tags must use the format vX.Y.Z with an optional prerelease suffix (e.g. v1.2.3-alpha)" exit 1 fi jq --arg tag "$RELEASE_TAG" '.versions = [$tag] + (.versions - [$tag])' \