docs: update API doc versions on stable releases

.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]+(-[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])' \
+            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
 

.gitignore

@@ -88,6 +88,7 @@ coverage.xml
 *.swo
 *.sublime-project
 *.sublime-workspace
+.scout/
 
 # macOS
 .DS_Store

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).
 

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.