ci(docs): add docs website automation

[pimlock]

Summary

Note

After this is merged, docs publishing won't change. The state after this is merged is that we have new manual actions that modify the docs-website branch. That branch will later become the source for publishing (see comments under #1296 for more details)

• add a manual sync-docs.yml workflow that syncs or removes a single docs snapshot on the generated docs-website branch
• add a manual publish-docs-website.yml workflow for Fern preview or explicit production publishing from docs-website
• add tasks/scripts/sync_docs_website.py with inline uv dependencies and YAML-based Fern config updates

Tip

Preview build: https://nvidia-preview-multi-version-spike.docs.buildwithfern.com/openshell/

Related Issue

• feat(docs): publish versioned Fern docs for releases #1296

Changes

• sync-docs.yml supports operation=sync|remove, channel=dev|latest|version, source_ref, version_slug, and display_name.
• Sync runs one job at a time with concurrency.group: docs-website and commits only when generated files change.
• Sync updates only the requested snapshot directory and preserves historical snapshots unless their slug is explicitly synced or removed.
• Publish runs manually from docs-website, validates with Fern, then publishes either preview or production based on the selected mode.

Next Steps

After the manual sync/publish path proves stable, wire this into the release workflows in a follow-up PR:

1. Make the docs workflows reusable while keeping manual dispatch.

   • Add workflow_call inputs to sync-docs.yml matching the existing workflow_dispatch inputs.
   • Add workflow_call inputs to publish-docs-website.yml for mode and preview_id.
   • Keep workflow_dispatch so maintainers can still manually sync/remove versions and manually publish previews.

2. Update .github/workflows/release-dev.yml.

   • Add a docs sync job after the dev release artifacts are published.
   • Call sync-docs.yml with operation=sync, channel=dev, and source_ref=${{ github.sha }}.
   • Follow it with a production publish job that calls publish-docs-website.yml with mode=production so /openshell/dev/... updates on the live docs site.
   • Rely on the existing docs-website concurrency group so dev docs syncs cannot race tag docs syncs.

3. Update .github/workflows/release-tag.yml.

4. Keep historical versions explicit.

   • Continue using manual sync-docs.yml runs for selected historical versions, e.g. operation=sync, channel=version, source_ref=v0.0.36, version_slug=v0.0.36.
   • Continue using manual operation=remove for versions we intentionally drop.
   • Decide separately whether to add last-N release retention.

Using workflow_call rather than gh workflow run keeps release jobs synchronous: the release workflow can wait for docs sync and publish to finish, and failures show up in the release run instead of in a detached workflow run.

Testing

• python3 -m py_compile tasks/scripts/sync_docs_website.py
• uv run tasks/scripts/sync_docs_website.py --help
• git diff --cached --check
• Local sync trial into the generated docs-website worktree:
  • synced dev
  • synced latest from v0.0.57
  • synced historical v0.0.36
  • synced and then removed demo v0.0.48
• mise run docs on the generated docs-website branch: 0 errors, existing Fern warnings only

Notes

• The generated docs-website branch has already been published separately.
• Workflows are manual-first; release workflow hooks should be added after this path proves stable.

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[pimlock]

/ok to test b94a83b