build-fern-docs.yml

name: Build Fern docs

on:
  workflow_dispatch:
    inputs:
      use_cache:
        description: "Use cached notebooks for unchanged sources"
        type: boolean
        default: true
      release_tag:
        description: "Release tag to publish. Defaults to the latest published release without creating a new snapshot."
        type: string
        required: false
      source_ref:
        description: "Source ref for release docs. Defaults to release_tag when set, otherwise the workflow ref."
        type: string
        required: false
  release:
    types:
      - published

permissions: {}

concurrency:
  group: fern-docs-website
  cancel-in-progress: false

env:
  FERN_PUBLISHED_BRANCH: docs-website

jobs:
  resolve-release:
    if: github.event_name != 'release' || github.event.release.prerelease != true
    runs-on: ubuntu-latest
    outputs:
      prepare_release_docs: ${{ steps.release.outputs.prepare_release_docs }}
      release_tag: ${{ steps.release.outputs.release_tag }}
      source_ref: ${{ steps.release.outputs.source_ref }}
    permissions:
      contents: read
    steps:
      - name: Resolve release inputs
        id: release
        env:
          GH_TOKEN: ${{ github.token }}
          EVENT_NAME: ${{ github.event_name }}
          EVENT_RELEASE_TAG: ${{ github.event.release.tag_name }}
          INPUT_RELEASE_TAG: ${{ inputs.release_tag }}
          INPUT_SOURCE_REF: ${{ inputs.source_ref }}
          WORKFLOW_REF: ${{ github.ref }}
        run: |
          if [ "$EVENT_NAME" = "release" ]; then
            release_tag="$EVENT_RELEASE_TAG"
            source_ref="${INPUT_SOURCE_REF:-$EVENT_RELEASE_TAG}"
            prepare_release_docs=1
          elif [ -n "$INPUT_RELEASE_TAG" ]; then
            release_tag="$INPUT_RELEASE_TAG"
            source_ref="${INPUT_SOURCE_REF:-$INPUT_RELEASE_TAG}"
            prepare_release_docs=1
          else
            release_tag=$(gh release list --repo "$GITHUB_REPOSITORY" --exclude-drafts --exclude-pre-releases --limit 1 --json tagName --jq '.[0].tagName // empty')
            if [ -z "$release_tag" ]; then
              echo "::error::Could not find the latest published release tag."
              exit 1
            fi
            source_ref="${INPUT_SOURCE_REF:-$WORKFLOW_REF}"
            prepare_release_docs=0
          fi

          echo "prepare_release_docs=$prepare_release_docs" >> "$GITHUB_OUTPUT"
          echo "release_tag=$release_tag" >> "$GITHUB_OUTPUT"
          echo "source_ref=$source_ref" >> "$GITHUB_OUTPUT"

  prepare-published-release:
    if: needs.resolve-release.outputs.prepare_release_docs == '1'
    needs: resolve-release
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: Checkout workflow
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          path: workflow
          ref: ${{ github.event_name == 'workflow_dispatch' && github.ref || github.event.repository.default_branch }}

      - name: Checkout source
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0
          path: source
          ref: ${{ needs.resolve-release.outputs.source_ref }}

      - name: Checkout rolling source
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          path: rolling-source
          ref: ${{ github.event.repository.default_branch }}

      - name: Checkout published branch
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0
          path: website

      - name: Prepare published branch checkout
        working-directory: website
        run: |
          if ! git ls-remote --exit-code --heads origin "$FERN_PUBLISHED_BRANCH" >/dev/null 2>&1; then
            echo "::error::$FERN_PUBLISHED_BRANCH does not exist. Initialize it with the historical Fern archive before publishing."
            exit 1
          fi

          git fetch origin "$FERN_PUBLISHED_BRANCH" --depth=1
          git checkout -B "$FERN_PUBLISHED_BRANCH" FETCH_HEAD

      - name: Prepare Fern release snapshot
        env:
          RELEASE_TAG: ${{ needs.resolve-release.outputs.release_tag }}
          SOURCE_REF: ${{ needs.resolve-release.outputs.source_ref }}
          SOURCE_REPOSITORY: ${{ github.repository }}
          PUBLISHED_BRANCH: ${{ env.FERN_PUBLISHED_BRANCH }}
        run: |
          source_sha=$(git -C source rev-parse HEAD)
          python3 workflow/fern/scripts/fern-published-branch.py sync-source \
            --source-root source \
            --published-root website \
            --metadata-source-repository "$SOURCE_REPOSITORY" \
            --metadata-source-ref "$SOURCE_REF" \
            --metadata-source-sha "$source_sha" \
            --metadata-release-tag "$RELEASE_TAG" \
            --metadata-published-branch "$PUBLISHED_BRANCH"
          python3 workflow/fern/scripts/fern-release-version.py --root website/fern prepare --version "$RELEASE_TAG" --force
          python3 workflow/fern/scripts/fern-release-version.py --root website/fern check --version "$RELEASE_TAG" --require-latest-matches-release

      - name: Restore rolling Dev Notes and Recipes
        run: |
          python3 workflow/fern/scripts/fern-published-branch.py patch-devnotes \
            --source-root rolling-source \
            --published-root website

      - name: Install uv
        # Keep v8.1.0 until manual workflow dispatch is verified on newer releases.
        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
        with:
          version: "0.9.5"
          prune-cache: true

      - name: Set up Python
        run: uv python install 3.13

      - name: Install docs dependencies
        working-directory: website
        run: uv sync --python 3.13 --all-packages --group docs --group notebooks

      - name: Check Fern docs
        working-directory: website
        run: make check-fern-docs

      - name: Publish source notebook snapshot
        env:
          GH_TOKEN: ${{ github.token }}
          RELEASE_TAG: ${{ needs.resolve-release.outputs.release_tag }}
          SOURCE_REPOSITORY: ${{ github.repository }}
        working-directory: website
        run: |
          archive="$RUNNER_TEMP/fern-notebooks-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}-source-fallback.tar.gz"
          bash ../workflow/docs/scripts/fern_notebook_snapshot.sh \
            create . "$RELEASE_TAG" source-fallback "$archive"
          gh release upload "$RELEASE_TAG" "$archive" --repo "$SOURCE_REPOSITORY"

      - name: Commit published branch
        env:
          DEFAULT_BRANCH: ${{ github.event.repository.default_branch }}
          RELEASE_TAG: ${{ needs.resolve-release.outputs.release_tag }}
          SOURCE_REF: ${{ needs.resolve-release.outputs.source_ref }}
          SOURCE_REPOSITORY: ${{ github.repository }}
        working-directory: website
        run: |
          if [ -z "$(git status --porcelain)" ]; then
            echo "::notice::Fern published branch already has $RELEASE_TAG."
            exit 0
          fi

          source_sha=$(git -C ../source rev-parse HEAD)
          rolling_sha=$(git -C ../rolling-source rev-parse HEAD)
          previous_published_sha=$(git rev-parse HEAD)
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git add -A
          git commit \
            -m "docs: publish Fern docs for $RELEASE_TAG" \
            -m "Source: $SOURCE_REPOSITORY@$SOURCE_REF ($source_sha)" \
            -m "Rolling Dev Notes and Recipes: $SOURCE_REPOSITORY@$DEFAULT_BRANCH ($rolling_sha)" \
            -m "Previous docs-website head: $previous_published_sha"
          git push origin HEAD:"$FERN_PUBLISHED_BRANCH"

  build-notebooks:
    needs: resolve-release
    uses: ./.github/workflows/build-notebooks.yml
    permissions:
      actions: read
      contents: write
    with:
      use_cache: ${{ github.event_name == 'release' || inputs.use_cache }}
      checkout_ref: ${{ needs.resolve-release.outputs.prepare_release_docs == '1' && needs.resolve-release.outputs.source_ref || needs.resolve-release.outputs.release_tag }}
    secrets: inherit

  publish:
    if: always() && needs.resolve-release.result == 'success' && (needs.prepare-published-release.result == 'success' || needs.prepare-published-release.result == 'skipped') && (needs.build-notebooks.result == 'success' || needs.build-notebooks.result == 'failure')
    needs:
      - resolve-release
      - prepare-published-release
      - build-notebooks
    runs-on: ubuntu-latest
    permissions:
      contents: write
    env:
      FERN_TOKEN: ${{ secrets.DOCS_FERN_TOKEN }}
    steps:
      - name: Checkout workflow
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          path: workflow
          ref: ${{ github.event_name == 'workflow_dispatch' && github.ref || github.event.repository.default_branch }}

      - name: Checkout published branch
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0
          path: website
          ref: ${{ env.FERN_PUBLISHED_BRANCH }}

      - name: Install uv
        # Keep v8.1.0 until manual workflow dispatch is verified on newer releases.
        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
        with:
          version: "0.9.5"
          prune-cache: true

      - name: Set up Python
        run: uv python install 3.13

      - name: Install docs dependencies
        working-directory: website
        run: uv sync --python 3.13 --all-packages --group docs --group notebooks

      - name: Download executed notebooks
        if: needs.build-notebooks.result == 'success'
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          name: notebooks
          path: website/docs/notebooks

      - name: Restore prepared notebook snapshot
        if: needs.build-notebooks.result == 'failure'
        env:
          GH_TOKEN: ${{ github.token }}
          SOURCE_REPOSITORY: ${{ github.repository }}
        working-directory: website
        run: |
          if [ ! -f fern/notebook-snapshot.json ]; then
            echo "::error::No canonical notebook snapshot is published. Run the Build Fern docs workflow successfully once."
            exit 1
          fi
          release_tag=$(jq -er '.release_tag' fern/notebook-snapshot.json)
          asset=$(jq -er '.asset' fern/notebook-snapshot.json)
          snapshot_dir="$RUNNER_TEMP/fern-notebook-snapshot"
          mkdir -p "$snapshot_dir"
          gh release download "$release_tag" --repo "$SOURCE_REPOSITORY" \
            --pattern "$asset" --dir "$snapshot_dir"
          bash ../workflow/docs/scripts/fern_notebook_snapshot.sh \
            restore . "$snapshot_dir/$asset"

      - name: Report notebook fallback
        if: needs.build-notebooks.result == 'failure'
        run: echo "::warning::Notebook execution failed; publishing the prepared source notebook snapshot."

      - name: Check Fern docs with executed notebooks
        if: needs.build-notebooks.result == 'success'
        working-directory: website
        run: make check-fern-docs

      - name: Check Fern docs with prepared notebooks
        if: needs.build-notebooks.result == 'failure'
        working-directory: website
        run: make check-fern-published-docs

      - name: Publish executed notebook snapshot
        if: needs.build-notebooks.result == 'success'
        env:
          GH_TOKEN: ${{ github.token }}
          RELEASE_TAG: ${{ needs.resolve-release.outputs.release_tag }}
          SOURCE_REPOSITORY: ${{ github.repository }}
        working-directory: website
        run: |
          archive="$RUNNER_TEMP/fern-notebooks-${GITHUB_RUN_ID}-${GITHUB_RUN_ATTEMPT}-executed.tar.gz"
          bash ../workflow/docs/scripts/fern_notebook_snapshot.sh \
            create . "$RELEASE_TAG" executed "$archive"
          gh release upload "$RELEASE_TAG" "$archive" --repo "$SOURCE_REPOSITORY"

      - name: Commit executed notebook snapshot
        if: needs.build-notebooks.result == 'success'
        env:
          RELEASE_TAG: ${{ needs.resolve-release.outputs.release_tag }}
          SOURCE_REPOSITORY: ${{ github.repository }}
        working-directory: website
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git add fern/notebook-snapshot.json
          if git diff --cached --quiet; then
            echo "::notice::Fern notebook snapshot is already current for $RELEASE_TAG."
            exit 0
          fi
          git commit \
            -m "docs: update Fern notebooks for $RELEASE_TAG" \
            -m "Source: $SOURCE_REPOSITORY@$RELEASE_TAG" \
            -m "Snapshot mode: executed"
          git push origin HEAD:"$FERN_PUBLISHED_BRANCH"

      - name: Publish Fern docs
        working-directory: website
        run: |
          if [ -z "$FERN_TOKEN" ]; then
            echo "::error::DOCS_FERN_TOKEN secret is required to publish Fern docs."
            exit 1
          fi

          cd fern
          fern_version=$(jq -r .version fern.config.json)
          if [[ ! "$fern_version" =~ ^[0-9]+[.][0-9]+[.][0-9]+([-.][0-9A-Za-z]+)*$ ]]; then
            echo "::error::Invalid Fern version in fern.config.json: $fern_version"
            exit 1
          fi

          npx -y "fern-api@$fern_version" generate --docs --no-prompt

      - name: Verify published docs
        env:
          PREPARE_RELEASE_DOCS: ${{ needs.resolve-release.outputs.prepare_release_docs }}
          RELEASE_TAG: ${{ needs.resolve-release.outputs.release_tag }}
        run: |
          urls=("https://docs.nvidia.com/nemo/datadesigner/latest/getting-started/welcome")
          if [ "$PREPARE_RELEASE_DOCS" = "1" ]; then
            release_slug="${RELEASE_TAG#refs/tags/}"
            if [[ "$release_slug" != v* ]]; then
              release_slug="v$release_slug"
            fi
            urls+=("https://docs.nvidia.com/nemo/datadesigner/$release_slug/getting-started/welcome")
          fi

          for url in "${urls[@]}"; do
            curl --fail --location --silent --show-error \
              --retry 12 --retry-all-errors --retry-delay 10 --retry-max-time 180 \
              "$url" >/dev/null
            echo "Verified $url"
          done