validate-docs-site.yaml

name: Validate docs site (render, test, and deploy)

on:
  pull_request:
    types: [opened, synchronize, ready_for_review]

permissions:
  issues: write
  pull-requests: write

jobs:
  validate:
    runs-on: ubuntu-latest
    if: github.event.pull_request.draft == false

    steps:
    - name: Check out documentation repository
      uses: actions/checkout@v4

    # Reclaim space + create a reserve for deterministic headroom
    - name: Free space + create reserve
      uses: ./.github/actions/free-disk-space
      with:
        remove_dotnet: "true"
        remove_android: "true"
        remove_haskell: "true"
        prune_docker: "true"
        apt_cleanup: "true"
        create_reserve_gb: "3"

    - name: Check out validmind-library repository
      uses: actions/checkout@v4
      with:
        repository: validmind/validmind-library
        path: site/_source/validmind-library
        token: ${{ secrets.DOCS_CI_RO_PAT }}

    - name: Check out installation repository
      uses: actions/checkout@v4
      with:
        repository: validmind/installation
        path: site/_source/installation
        token: ${{ secrets.DOCS_CI_RO_PAT }}
        sparse-checkout: |
          site/installation
        sparse-checkout-cone-mode: true

    - name: Check out release-notes repository
      uses: actions/checkout@v4
      with:
        repository: validmind/release-notes
        path: site/_source/release-notes
        token: ${{ secrets.DOCS_CI_RO_PAT }}
        sparse-checkout: |
          releases
        sparse-checkout-cone-mode: true

    - name: Check out backend repository
      uses: actions/checkout@v4
      with:
        repository: validmind/backend
        path: site/_source/backend
        token: ${{ secrets.DOCS_CI_RO_PAT }}
        sparse-checkout: |
          src/backend/templates/documentation/model_documentation
        sparse-checkout-cone-mode: true

    - name: Verify copyright headers
      run: |
        cd site
        make verify-copyright

    - name: Set up Quarto
      uses: quarto-dev/quarto-actions/setup@v2
      with:
        version: pre-release

    - name: Install Poetry
      run: |
        curl -sSL https://install.python-poetry.org | python3 -
        echo "$HOME/.local/bin" >> $GITHUB_PATH

    - name: Generate Python library docs
      run: |
        cd site/_source/validmind-library
        make install && make quarto-docs
        cd ../../
        rm -rf validmind
        mkdir -p validmind
        rsync -av --exclude '_build' --exclude 'templates' _source/validmind-library/docs/ validmind/

    - name: Generate template schema docs
      run: |
        pip install json-schema-for-humans
        BACKEND_ROOT=site/_source/backend python scripts/generate_template_schema_docs.py

    - name: Populate installation
      run: cp -r site/_source/installation/site/installation site/installation

    - name: Populate release notes
      run: |
        cp -r site/_source/release-notes/releases site
        rm -f site/releases/backend-releases.qmd site/releases/cmvm-releases.qmd

    - name: Render demo docs site
      run: |
          cd site
          quarto render --profile development 2>&1 | tee render_errors.log || {
          echo "Quarto render failed immediately";
          cat render_errors.log;
          exit 1;
          }
          make generate-sitemap

    - name: Add robots.txt for PR preview
      run: cp site/environments/robots-staging.txt site/_site/robots.txt

    - name: Test for warnings or errors
      run: |
        if grep -q 'WARN\|WARNING\|ERROR:' site/render_errors.log; then
          echo "Warnings or errors detected during Quarto render"
          cat site/render_errors.log
          exit 1
        else
          echo "No warnings or errors detected during Quarto render"
        fi

    # Demo bucket is in us-east-1
    - name: Configure AWS credentials
      run: aws configure set aws_access_key_id ${{ secrets.AWS_ACCESS_KEY_ID_STAGING }} && aws configure set aws_secret_access_key ${{ secrets.AWS_SECRET_ACCESS_KEY_STAGING }} && aws configure set default.region us-east-1

    - name: Deploy PR preview
      run: aws s3 sync site/_site s3://validmind-docs-staging/site/pr_previews/${{ github.head_ref }} --delete --exclude "notebooks/EXECUTED/*" && aws cloudfront create-invalidation --distribution-id ESWVTZYFL873V --paths "/*" --no-cli-pager

    - name: Post comment with preview URL
      uses: actions/github-script@v6
      with:
        script: |
          const previewUrl = `https://docs-staging.validmind.ai/pr_previews/${{ github.head_ref }}/index.html`;

          // Delete old preview comments
          const { data: comments } = await github.rest.issues.listComments({
            owner: context.repo.owner,
            repo: context.repo.repo,
            issue_number: context.issue.number,
          });
          for (const comment of comments) {
            if (comment.user.login === 'github-actions[bot]' && comment.body.includes('## Validate docs site')) {
              await github.rest.issues.deleteComment({
                owner: context.repo.owner,
                repo: context.repo.repo,
                comment_id: comment.id,
              });
            }
          }

          let comment = `## Validate docs site\n\n`;
          comment += `✓ INFO: A live preview of the docs site is available — [Open the preview](${previewUrl})\n\n`;

          github.rest.issues.createComment({
            owner: context.repo.owner,
            repo: context.repo.repo,
            issue_number: context.issue.number,
            body: comment
          });

    - name: Install pandoc
      run: |
        sudo apt-get update
        sudo apt-get install -y pandoc

    - name: Validate LLM markdown render
      run: bash llm/render.sh && bash llm/clean.sh
      working-directory: site

    # Release headroom and shrink before final lightweight steps & post-job
    - name: Release reserve & shrink
      if: always()
      uses: ./.github/actions/free-disk-space
      with:
        release_reserve: "true"
        remove_paths: |
          site/_source/installation
          site/_source/release-notes
          site/_source/backend
          site/render_errors.log
          site/_freeze
          dev.env
          valid.env

    - name: Final disk usage
      if: always()
      run: df -hT /