dev-docs-sync.yml

# This code is a Qiskit project.
#
# (C) Copyright IBM 2024.
#
# This code is licensed under the Apache License, Version 2.0. You may
# obtain a copy of this license in the LICENSE file in the root directory
# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
#
# Any modifications or derivative works of this code must retain this
# copyright notice, and modified files need to carry a notice indicating
# that they have been altered from the originals.

name: Dev docs sync
on:
  workflow_dispatch:
  schedule:
    - cron: "0 1 * * 1,3,5" # At 01:00 on Monday, Wednesday, and Friday.

jobs:
  sync:
    runs-on: ubuntu-latest
    if: github.repository_owner == 'Qiskit'
    steps:
      - uses: actions/checkout@v4
      - name: Set up Node.js
        uses: actions/setup-node@v4
        with:
          node-version: 24
      - name: Install dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y imagemagick
          sudo ln -s /usr/bin/convert /usr/bin/magick
          npm ci

      - name: Sync dev docs
        run: npx tsx scripts/js/commands/api/syncDevDocs.ts
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Get all changed docs files
        id: changed-docs-files
        # Note: we specifically check for changed docs files rather than changed
        # images in public/images or changes to scripts/config/api-html-artifacts.json
        # to avoid noisy PRs. It's common for images to change because some of the
        # images are generated non-deterministically.
        run: |
          echo "CHANGED_FILES<<EOF" >> $GITHUB_OUTPUT
          git diff --name-only docs >> $GITHUB_OUTPUT
          echo "EOF" >> $GITHUB_OUTPUT

      - name: Make pull request
        if: steps.changed-docs-files.outputs.CHANGED_FILES
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git config user.name "github-actions[bot]"
          git switch -c actions/cron-${{ github.run_id }}
          git add .
          git commit -m "Sync latest dev docs"
          git push origin actions/cron-${{ github.run_id }}
          gh pr create \
           -B main \
           -H actions/cron-${{ github.run_id }} \
           --title "Update API dev docs" \
           --body "This PR updates all dev APIs that changed since the last sync. \
           If there is a merge conflict, usually you can close the PR and use the \
           next dev docs PR. \

          > [!NOTE]
          > This pull request was created by a GitHub action.

          ### What is this PR?

          We host \"dev\" API docs (e.g. \
          https://quantum.cloud.ibm.com/docs/en/api/qiskit-ibm-runtime/dev), \
          which are generated from the `main` branch of the project's repo. \
          This helps us preview upcoming changes and helps any users that are \
          using the `main` branch rather than a specific release. \

          This PR updates the dev API docs 

          ### How to deal with this PR

          1. Glance through the diff and check things look reasonable. Only \
             the dev docs and supporting images should be changed. \
             It's common for there to be new pages. While sometimes \
             a page or API will be removed, we should not be deleting \
             a substantial portion of the docs.

          2. If it looks good, approve the PR.

          3. Close and re-open this PR to trigger CI; the action is not \
             allowed to trigger CI properly so we need a human with write \
             access to trigger it.

          4. Once CI has passed, you can merge this PR. \
             If something goes wrong, consider asking an engineer \
             for help. With broken links, we sometimes need to update \
             the original API docs to fix the bad link, such as \
             updating the Qiskit SDK in Qiskit/qiskit." \
          --reviewer abbycross \
          --reviewer beckykd \
          --reviewer kaelynj