docusaurus_sync.yml

name: Sync API reference with Docusaurus

on:
  push:
    tags:
      - "v[0-9]+.[0-9]+.[0-9]+*"

  # Manual trigger: Use this ONLY if the automatic API reference sync failed during a release.
  # This will regenerate and sync the API reference to the Haystack repository.
  # WARNING: Running this workflow when this repository has evolved significantly since the release
  # will sync an incorrect API reference to Haystack.
  workflow_dispatch:

env:
  HATCH_VERSION: "1.16.5"
  PYTHON_VERSION: "3.11"
jobs:
  generate-api-reference:
    runs-on: ubuntu-slim

    steps:
      - name: Checkout this repo
        uses: actions/checkout@v5

      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: "${{ env.PYTHON_VERSION }}"

      - name: Install Hatch
        run: pip install hatch==${{ env.HATCH_VERSION }}

      - name: Generate API reference
        run: hatch run docs

      - name: Upload API reference artifact
        uses: actions/upload-artifact@v7
        with:
          name: experimental-api-reference
          path: tmp_api_reference
          if-no-files-found: error
          retention-days: 1
          overwrite: true


  sync-api-reference:
    runs-on: ubuntu-slim
    needs: generate-api-reference

    steps:
      - name: Checkout Haystack repo
        uses: actions/checkout@v6
        with:
          repository: deepset-ai/haystack
          ref: main
          token: ${{ secrets.HAYSTACK_BOT_TOKEN }}

      - name: Set up Python
        uses: actions/setup-python@v6
        with:
          python-version: "${{ env.PYTHON_VERSION }}"

      - name: Download API reference artifact
        uses: actions/download-artifact@v8
        with:
          name: experimental-api-reference
          path: tmp_api_reference

      - name: Sync API reference
        run: |
          # Function to sync generated API reference to a destination
          sync_to_dest() {
            echo "Syncing to $1"
            mkdir -p "$1"
            rsync -av --delete --exclude='.git/' "tmp_api_reference/" "$1/"
          }

          # Sync to main reference
          sync_to_dest "docs-website/reference/experiments-api"

          # Sync to all versioned directories
          if [ -d "docs-website/reference_versioned_docs" ]; then
            for version_dir in "docs-website/reference_versioned_docs"/version-*; do
              [ -d "$version_dir" ] && sync_to_dest "$version_dir/experiments-api"
            done
          fi

      - name: Create Pull Request
        uses: peter-evans/create-pull-request@v8
        with:
          token: ${{ secrets.HAYSTACK_BOT_TOKEN }}
          commit-message: "Sync Haystack Experimental API reference on Docusaurus"
          branch: sync-docusaurus-api-reference-experimental
          base: main
          title: "docs: sync Haystack Experimental API reference on Docusaurus"
          add-paths: |
            docs-website
          body: |
            This PR syncs the Haystack Experimental API reference on Docusaurus. Just approve and merge it.
          reviewers: "${{ github.actor }}"