fern-docs.yml

# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0

name: Fern Docs

on:
  push:
    branches:
      - main
      - 'pull-request/**'
    tags:
      - '*'
  pull_request:
    types:
      - closed
  workflow_dispatch:
    inputs:
      tag:
        description: 'Raw SemVer docs tag, such as 0.1.0 or 0.1.0-rc.1. Alpha tags are not published.'
        required: false
        type: string

concurrency:
  group: '${{ github.workflow }} @ ${{ github.event_name }} @ ${{ github.head_ref || github.ref }}'
  cancel-in-progress: true

jobs:
  changed-files:
    name: Detect docs changes
    if: ${{ github.ref_type != 'tag' && github.event_name != 'pull_request' }}
    runs-on: ubuntu-latest
    timeout-minutes: 10
    permissions:
      contents: read
    outputs:
      docs: ${{ github.event_name == 'workflow_dispatch' || steps.filter.outputs.docs == 'true' }}
    steps:
      - name: Checkout
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          fetch-depth: 0

      - name: Detect changed paths
        id: filter
        if: ${{ github.event_name != 'workflow_dispatch' }}
        uses: dorny/paths-filter@fbd0ab8f3e69293af611ebaee6363fc25e6d187d # v4.01
        with:
          filters: .github/ci-path-filters.yml

  preview-docs:
    name: Preview docs
    needs: changed-files
    if: >-
      ${{
        needs.changed-files.outputs.docs == 'true'
        && startsWith(github.ref_name, 'pull-request/')
      }}
    runs-on: ubuntu-latest
    environment: fern
    timeout-minutes: 60
    permissions:
      contents: read
      pull-requests: write
    env:
      NEMO_RELAY_CI_WORKSPACE: ${{ github.workspace }}/source-checkout
      UV_PYTHON_DOWNLOADS: never
    steps:
      - name: Checkout source branch
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          path: source-checkout
          fetch-depth: 1

      - name: Load CI tool versions
        id: ci-config
        uses: ./source-checkout/.github/actions/load-ci-tool-versions

      - name: Setup uv
        uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8
        with:
          version: ${{ steps.ci-config.outputs.uv_version }}
          enable-cache: true
          cache-dependency-glob: ${{ github.workspace }}/source-checkout/uv.lock

      - name: Setup Node.js
        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6
        with:
          node-version: ${{ steps.ci-config.outputs.node_version }}

      - name: Setup Rust
        uses: actions-rust-lang/setup-rust-toolchain@150fca883cd4034361b621bd4e6a9d34e5143606 # v1.15.4
        with:
          cache: false
          toolchain: ${{ steps.ci-config.outputs.rust_version }}
          rustflags: ""

      - name: Cache Rust docs dependencies
        uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
        with:
          shared-key: nemo-relay-rust-docs-${{ runner.os }}-${{ runner.arch }}-${{ steps.ci-config.outputs.rust_version }}
          workspaces: source-checkout -> source-checkout/target
          cache-all-crates: true
          cache-bin: false
          save-if: false

      - name: Install managed Python
        working-directory: source-checkout
        run: |
          set -euo pipefail
          UV_PYTHON_DOWNLOADS=manual uv python install --managed-python ${{ steps.ci-config.outputs.default_python_version }}

      - name: Install just
        uses: taiki-e/install-action@c070f87102a1c75b3183910f391c1cb887fe13c8 # v2.77.6
        with:
          tool: just@${{ steps.ci-config.outputs.just_version }}

      - name: Install documentation dependencies
        working-directory: source-checkout
        run: |
          set -euo pipefail
          uv sync --no-default-groups --group dev --no-install-project
          npm ci --ignore-scripts

      - name: Generate and validate source docs
        working-directory: source-checkout
        env:
          NEMO_RELAY_DOCS_DEPS_READY: "1"
          FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
        run: just docs

      - name: Checkout docs website branch
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          ref: docs-website
          path: docs-checkout
          fetch-depth: 1

      - name: Sync docs website layout
        working-directory: source-checkout
        run: |
          set -euo pipefail
          uv run --no-sync python scripts/docs/sync_fern_docs_branch.py sync-dev \
            --source-root "$GITHUB_WORKSPACE/source-checkout" \
            --target-root "$GITHUB_WORKSPACE/docs-checkout"

      - name: Generate docs preview
        id: preview
        working-directory: docs-checkout/fern
        env:
          FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
        run: |
          set -euo pipefail
          pr_number="${GITHUB_REF_NAME#pull-request/}"
          printf 'pr_number=%s\n' "$pr_number" >> "$GITHUB_OUTPUT"
          preview_id="pull-request-${pr_number}"
          if OUTPUT="$("$GITHUB_WORKSPACE/source-checkout/node_modules/.bin/fern" generate --docs --preview --id "$preview_id" 2>&1)"; then
            fern_exit=0
          else
            fern_exit=$?
          fi
          printf '%s\n' "$OUTPUT"
          if [[ "$fern_exit" -ne 0 ]]; then
            echo "::error::Fern docs preview generation failed"
            exit "$fern_exit"
          fi
          url="$(printf '%s\n' "$OUTPUT" | sed -n 's/^.*Published docs to //p' | tail -n 1)"
          if [[ -n "$url" ]]; then
            printf 'url=%s\n' "$url" >> "$GITHUB_OUTPUT"
          fi

      - name: Comment preview URL on PR
        if: ${{ steps.preview.outputs.url != '' }}
        uses: marocchino/sticky-pull-request-comment@0ea0beb66eb9baf113663a64ec522f60e49231c0 # v3.0.4
        with:
          header: nemo-relay-fern-preview
          number: ${{ steps.preview.outputs.pr_number }}
          message: 'Fern docs preview: ${{ steps.preview.outputs.url }}'

  cleanup-preview-docs:
    name: Clean up docs preview
    if: >-
      ${{
        github.event_name == 'pull_request'
        && github.event.action == 'closed'
        && github.event.pull_request.merged == true
      }}
    runs-on: ubuntu-latest
    environment: fern
    timeout-minutes: 10
    permissions:
      contents: read
    env:
      UV_PYTHON_DOWNLOADS: never
    steps:
      - name: Checkout source branch
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          ref: ${{ github.event.pull_request.base.ref }}
          path: source-checkout
          fetch-depth: 1
          persist-credentials: false

      - name: Load CI tool versions
        id: ci-config
        uses: ./source-checkout/.github/actions/load-ci-tool-versions

      - name: Setup Node.js
        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6
        with:
          node-version: ${{ steps.ci-config.outputs.node_version }}
          package-manager-cache: false

      - name: Install Fern CLI
        working-directory: source-checkout
        run: |
          set -euo pipefail
          npm ci --ignore-scripts

      - name: Delete preview deployment
        working-directory: source-checkout/fern
        env:
          FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
          PR_NUMBER: ${{ github.event.pull_request.number }}
        run: |
          set -euo pipefail
          preview_id="pull-request-${PR_NUMBER}"
          echo "Deleting Fern docs preview: ${preview_id}"
          "$GITHUB_WORKSPACE/source-checkout/node_modules/.bin/fern" docs preview delete --id "$preview_id" \
            || echo "Fern preview deletion returned non-zero; it may already be deleted."

  publish-dev-docs:
    name: Publish dev docs
    needs: changed-files
    if: >-
      ${{
        needs.changed-files.outputs.docs == 'true'
        && (
          github.ref_name == 'main'
          || (github.event_name == 'workflow_dispatch' && (inputs.tag == '' || inputs.tag == null))
        )
      }}
    runs-on: ubuntu-latest
    environment: fern
    timeout-minutes: 60
    permissions:
      contents: write
    env:
      NEMO_RELAY_CI_WORKSPACE: ${{ github.workspace }}/source-checkout
      UV_PYTHON_DOWNLOADS: never
    steps:
      - name: Checkout source branch
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          path: source-checkout
          fetch-depth: 1

      - name: Load CI tool versions
        id: ci-config
        uses: ./source-checkout/.github/actions/load-ci-tool-versions

      - name: Setup uv
        uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8
        with:
          version: ${{ steps.ci-config.outputs.uv_version }}
          enable-cache: true
          cache-dependency-glob: ${{ github.workspace }}/source-checkout/uv.lock

      - name: Setup Node.js
        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6
        with:
          node-version: ${{ steps.ci-config.outputs.node_version }}

      - name: Setup Rust
        uses: actions-rust-lang/setup-rust-toolchain@150fca883cd4034361b621bd4e6a9d34e5143606 # v1.15.4
        with:
          cache: false
          toolchain: ${{ steps.ci-config.outputs.rust_version }}
          rustflags: ""

      - name: Cache Rust docs dependencies
        uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
        with:
          shared-key: nemo-relay-rust-docs-${{ runner.os }}-${{ runner.arch }}-${{ steps.ci-config.outputs.rust_version }}
          workspaces: source-checkout -> source-checkout/target
          cache-all-crates: true
          cache-bin: false
          save-if: false

      - name: Install managed Python
        working-directory: source-checkout
        run: |
          set -euo pipefail
          UV_PYTHON_DOWNLOADS=manual uv python install --managed-python ${{ steps.ci-config.outputs.default_python_version }}

      - name: Install just
        uses: taiki-e/install-action@c070f87102a1c75b3183910f391c1cb887fe13c8 # v2.77.6
        with:
          tool: just@${{ steps.ci-config.outputs.just_version }}

      - name: Install documentation dependencies
        working-directory: source-checkout
        run: |
          set -euo pipefail
          uv sync --no-default-groups --group dev --no-install-project
          npm ci --ignore-scripts

      - name: Generate and validate source docs
        working-directory: source-checkout
        env:
          NEMO_RELAY_DOCS_DEPS_READY: "1"
          FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
        run: just docs

      - name: Checkout docs website branch
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          ref: docs-website
          path: docs-checkout
          fetch-depth: 1
          token: ${{ secrets.GITHUB_TOKEN }}

      - name: Sync docs website layout
        working-directory: source-checkout
        run: |
          set -euo pipefail
          uv run --no-sync python scripts/docs/sync_fern_docs_branch.py sync-dev \
            --source-root "$GITHUB_WORKSPACE/source-checkout" \
            --target-root "$GITHUB_WORKSPACE/docs-checkout"

      - name: Check for docs website changes
        id: changes
        working-directory: docs-checkout
        run: |
          set -euo pipefail
          if [[ -z "$(git status --porcelain --untracked-files=all)" ]]; then
            echo "has_changes=false" >> "$GITHUB_OUTPUT"
          else
            echo "has_changes=true" >> "$GITHUB_OUTPUT"
            git status --short
          fi

      - name: Commit and push docs website changes
        if: ${{ steps.changes.outputs.has_changes == 'true' }}
        working-directory: docs-checkout
        run: |
          set -euo pipefail
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add -A
          git commit -m "docs(fern): sync dev from main

          Automated sync of docs/ from main.
          Source commit: ${{ github.sha }}"
          git push origin docs-website

      - name: Publish docs
        if: ${{ steps.changes.outputs.has_changes == 'true' }}
        working-directory: docs-checkout/fern
        env:
          FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
        run: |
          "$GITHUB_WORKSPACE/source-checkout/node_modules/.bin/fern" generate --docs

  release-version-docs:
    name: Release docs version
    if: >-
      ${{
        github.ref_type == 'tag'
        || (github.event_name == 'workflow_dispatch' && inputs.tag != '' && inputs.tag != null)
      }}
    runs-on: ubuntu-latest
    environment: fern
    timeout-minutes: 60
    permissions:
      contents: write
    env:
      NEMO_RELAY_CI_WORKSPACE: ${{ github.workspace }}/source-checkout
      UV_PYTHON_DOWNLOADS: never
    steps:
      - name: Determine version tag
        id: version
        env:
          EVENT_NAME: ${{ github.event_name }}
          INPUT_TAG: ${{ inputs.tag }}
        run: |
          set -euo pipefail
          if [[ "$EVENT_NAME" == "workflow_dispatch" ]]; then
            tag="$INPUT_TAG"
          else
            tag="${GITHUB_REF_NAME}"
          fi
          if [[ ! "$tag" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-(beta|rc)\.[0-9]+)?$ ]]; then
            echo "Error: docs tags must use raw SemVer such as 0.1.0, 0.1.0-beta.1, or 0.1.0-rc.1; alpha tags are not published" >&2
            exit 1
          fi
          printf 'tag=%s\n' "$tag" >> "$GITHUB_OUTPUT"

      - name: Checkout workflow tools
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          path: workflow-checkout
          fetch-depth: 1
          persist-credentials: false

      - name: Checkout source branch
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          ref: ${{ steps.version.outputs.tag }}
          path: source-checkout
          fetch-depth: 1

      - name: Load CI tool versions
        id: ci-config
        uses: ./source-checkout/.github/actions/load-ci-tool-versions

      - name: Setup uv
        uses: astral-sh/setup-uv@cec208311dfd045dd5311c1add060b2062131d57 # v8
        with:
          version: ${{ steps.ci-config.outputs.uv_version }}
          enable-cache: true
          cache-dependency-glob: ${{ github.workspace }}/source-checkout/uv.lock

      - name: Setup Node.js
        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6
        with:
          node-version: ${{ steps.ci-config.outputs.node_version }}

      - name: Setup Rust
        uses: actions-rust-lang/setup-rust-toolchain@150fca883cd4034361b621bd4e6a9d34e5143606 # v1.15.4
        with:
          cache: false
          toolchain: ${{ steps.ci-config.outputs.rust_version }}
          rustflags: ""

      - name: Cache Rust docs dependencies
        uses: Swatinem/rust-cache@c19371144df3bb44fab255c43d04cbc2ab54d1c4 # v2.9.1
        with:
          shared-key: nemo-relay-rust-docs-${{ runner.os }}-${{ runner.arch }}-${{ steps.ci-config.outputs.rust_version }}
          workspaces: source-checkout -> source-checkout/target
          cache-all-crates: true
          cache-bin: false
          save-if: false

      - name: Install managed Python
        working-directory: source-checkout
        run: |
          set -euo pipefail
          UV_PYTHON_DOWNLOADS=manual uv python install --managed-python ${{ steps.ci-config.outputs.default_python_version }}

      - name: Install just
        uses: taiki-e/install-action@c070f87102a1c75b3183910f391c1cb887fe13c8 # v2.77.6
        with:
          tool: just@${{ steps.ci-config.outputs.just_version }}

      - name: Install release docs dependencies
        working-directory: source-checkout
        run: |
          set -euo pipefail
          uv sync --no-default-groups --group dev --no-install-project
          npm ci --ignore-scripts

      - name: Generate source API references
        working-directory: source-checkout
        env:
          NEMO_RELAY_DOCS_DEPS_READY: "1"
        run: just docs-api-reference

      - name: Checkout docs website branch
        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
        with:
          ref: docs-website
          path: docs-checkout
          fetch-depth: 1
          token: ${{ secrets.GITHUB_TOKEN }}

      - name: Create docs snapshot
        working-directory: source-checkout
        run: |
          set -euo pipefail
          uv run --no-sync python "$GITHUB_WORKSPACE/workflow-checkout/scripts/docs/sync_fern_docs_branch.py" release-version \
            --source-root "$GITHUB_WORKSPACE/source-checkout" \
            --target-root "$GITHUB_WORKSPACE/docs-checkout" \
            --tag "${{ steps.version.outputs.tag }}"

      - name: Commit and push docs snapshot
        working-directory: docs-checkout
        run: |
          set -euo pipefail
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add -A
          if git diff --cached --quiet; then
            echo "No docs snapshot changes to commit."
            exit 0
          fi
          git commit -m "docs(fern): release version v${{ steps.version.outputs.tag }}

          Automated documentation snapshot.
          Source tag: ${{ steps.version.outputs.tag }}"
          git push origin docs-website

      - name: Publish docs
        working-directory: docs-checkout/fern
        env:
          FERN_TOKEN: ${{ secrets.FERN_TOKEN }}
        run: |
          "$GITHUB_WORKSPACE/source-checkout/node_modules/.bin/fern" generate --docs