chore: finalize v1 auto-generated docs rollout

Author: yaniv-golan

.github/scripts/check_and_update_docs.py

@@ -1,106 +1,69 @@
-name: Check Documentation Updates
+name: Sync Affinity v1 Docs
 
 on:
   schedule:
-    # Run daily at 00:00 UTC
-    - cron: '0 0 * * *'
+    - cron: "0 0 * * *"
   workflow_dispatch:
-    inputs:
-      api_version:
-        description: 'API version to check (v1, v2, or all)'
-        required: false
-        default: 'all'
-        type: choice
-        options:
-          - all
-          - v1
-          - v2
-      force_check:
-        description: 'Force check even if recently checked'
-        required: false
-        default: false
-        type: boolean
 
-jobs:
-  # Run tests first to ensure code quality before attempting updates
-  test:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-
-      - name: Set up Python
-        uses: actions/setup-python@v5
-        with:
-          python-version: '3.11'
-          cache: 'pip'
+permissions:
+  contents: write
+  pull-requests: write
 
-      - name: Install dependencies
-        run: |
-          python -m pip install --upgrade pip
-          pip install -r requirements-ci.txt
-
-      - name: Run tests
-        run: |
-          pytest tests/ -m "not integration" --tb=short
-
-  check-updates:
-    needs: test  # Only run if tests pass
+jobs:
+  sync-docs:
     runs-on: ubuntu-latest
-    permissions:
-      contents: write
-      pull-requests: write
-      issues: read
-
     steps:
       - name: Checkout repository
         uses: actions/checkout@v4
         with:
-          fetch-depth: 0  # Full history for diff generation
+          fetch-depth: 0
 
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: '3.11'
-          cache: 'pip'
+          python-version: "3.11"
+          cache: "pip"
 
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
           pip install -r requirements-ci.txt
 
-      - name: Install GitHub CLI
+      - name: Sync documentation
+        id: sync_docs
         run: |
-          type -p curl >/dev/null || sudo apt-get update && sudo apt-get install -y curl
-          curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
-          sudo chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg
-          echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
-          sudo apt-get update
-          sudo apt-get install -y gh
+          set +e
+          python tools/v1_sync_pipeline/sync_v1_docs.py --fail-on-diff
+          status=$?
+          set -e
+          if [ "$status" -eq 0 ]; then
+            echo "changes=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          if [ "$status" -eq 1 ]; then
+            echo "changes=true" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          exit "$status"
 
-      - name: Configure GitHub CLI
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-        run: |
-          gh auth setup-git
-          gh auth status
-
-      - name: Configure Git
-        run: |
-          git config --global user.name "github-actions[bot]"
-          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+      - name: Run link checker
+        run: python tools/v1_sync_pipeline/qa/check_links.py docs/v1/affinity_api_docs.md
 
-      - name: Check and update documentation
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          API_VERSION: ${{ github.event.inputs.api_version || 'all' }}
-          FORCE_CHECK: ${{ github.event.inputs.force_check || 'false' }}
-        run: |
-          python .github/scripts/check_and_update_docs.py --api-version "$API_VERSION" --force-check "$FORCE_CHECK"
+      - name: Create pull request
+        if: steps.sync_docs.outputs.changes == 'true'
+        uses: peter-evans/create-pull-request@v6
+        with:
+          commit-message: "chore: sync Affinity v1 docs"
+          title: "chore: sync Affinity v1 docs"
+          body: |
+            Automated sync of Affinity API v1 documentation.
+          branch: chore/sync-v1-docs
+          delete-branch: true
 
       - name: Summary
         if: always()
         run: |
-          echo "## Documentation Update Check Complete" >> $GITHUB_STEP_SUMMARY
-          echo "" >> $GITHUB_STEP_SUMMARY
-          echo "Check completed at $(date -u +'%Y-%m-%d %H:%M:%S UTC')" >> $GITHUB_STEP_SUMMARY
+          echo "## Sync summary" >> "$GITHUB_STEP_SUMMARY"
+          echo "" >> "$GITHUB_STEP_SUMMARY"
+          echo "- Changes detected: ${{ steps.sync_docs.outputs.changes || 'false' }}" >> "$GITHUB_STEP_SUMMARY"
+          echo "- Run completed at $(date -u +'%Y-%m-%d %H:%M:%S UTC')" >> "$GITHUB_STEP_SUMMARY"

.github/workflows/check-docs-updates.yml

@@ -26,13 +26,17 @@ jobs:
           python -m pip install --upgrade pip
           pip install -r requirements-ci.txt
 
+      - name: Ensure sync script is idempotent
+        run: |
+          python tools/v1_sync_pipeline/sync_v1_docs.py --fail-on-diff
+
       - name: Run unit tests
         run: |
           pytest tests/ -m "not integration" -v --tb=short
 
       - name: Run tests with coverage
         run: |
-          pytest tests/ -m "not integration" --cov=.github/scripts --cov-report=term-missing
+          pytest tests/ -m "not integration" --cov=tools/v1_sync_pipeline --cov-report=term-missing --cov-report=xml
 
       - name: Upload coverage reports
         if: always()

.github/workflows/tests.yml

@@ -0,0 +1 @@
+docs/v1/affinity_api_docs_legacy.md

.markdownlintignore

@@ -39,7 +39,7 @@ repos:
       - id: markdownlint
         args: [--fix, --config=.markdownlint.json]
         files: ^(docs/|README\.md|AGENTS\.md|.*\.md)$
-        exclude: ^docs/v1/affinity_api_docs\.md$  # Exclude large API docs - too many false positives
+        exclude: ^docs/v1/affinity_api_docs(_legacy)?\.md$  # Exclude large API docs - too many false positives
 
   # YAML linting
   - repo: https://github.com/adrienverge/yamllint