ci: deploy preview docs action (#66)

.github/actions/pin_comment/action.yml

@@ -0,0 +1,83 @@
+name: "Pin Comment"
+description: "Pins a comment by hiding it with HTML comments and a unique ID"
+
+inputs:
+  message:
+    description: "The message to pin"
+    required: true
+  token:
+    description: "GitHub token"
+    required: true
+  issue_number:
+    description: "The issue or PR number"
+    required: true
+  comment_id:
+    description: "Unique identifier for this pinned comment"
+    required: true
+  working_directory:
+    description: "Path to the repository working directory"
+    required: true
+
+runs:
+  using: "composite"
+  steps:
+    - name: Pin comment
+      shell: /usr/bin/bash --noprofile --norc -e -o pipefail {0}
+      env:
+        GITHUB_TOKEN: ${{ inputs.token }}
+        MESSAGE: ${{ inputs.message }}
+        ISSUE_NUMBER: ${{ inputs.issue_number }}
+        COMMENT_ID: ${{ inputs.comment_id }}
+        WORKING_DIRECTORY: ${{ inputs.working_directory }}
+      run: |
+        # Change to working directory
+        cd "${WORKING_DIRECTORY}"
+
+        # Create comment with hidden marker and ID
+        COMMENT="<!--pin-comment-marker-${COMMENT_ID}-->
+        ${MESSAGE}"
+
+        # Properly escape the comment for JSON
+        ESCAPED_COMMENT=$(echo "$COMMENT" | jq -R -s '.')
+
+        # Find and delete old comment with same ID using GitHub token
+        echo "Searching for existing pinned comment with ID: ${COMMENT_ID}"
+        response=$(curl -s -w "%{http_code}" -H "Authorization: token ${GITHUB_TOKEN}" \
+          "https://api.github.com/repos/${GITHUB_REPOSITORY}/issues/${ISSUE_NUMBER}/comments?per_page=100")
+        status_code=${response: -3}
+        comments=${response:0:-3}
+
+        if [ "$status_code" != "200" ]; then
+          echo "Failed to fetch comments. Status code: ${status_code}"
+          exit 1
+        fi
+
+        old_comment_id=$(echo "$comments" | jq -r ".[] | select(.body | startswith(\"<!--pin-comment-marker-${COMMENT_ID}-->\")) | .id")
+
+        # Update old comment if found
+        if [ ! -z "$old_comment_id" ]; then
+          echo "Updating existing comment with ID: ${old_comment_id}"
+          response=$(curl -s -w "%{http_code}" -X PATCH -H "Authorization: token ${GITHUB_TOKEN}" \
+            -H "Content-Type: application/json" \
+            -d "{\"body\":${ESCAPED_COMMENT}}" \
+            "https://api.github.com/repos/${GITHUB_REPOSITORY}/issues/comments/${old_comment_id}")
+          status_code=${response: -3}
+
+          if [ "$status_code" != "200" ]; then
+            echo "Failed to update comment. Status code: ${status_code}"
+            exit 1
+          fi
+        else
+          # Create new pinned comment using GitHub API directly
+          echo "Creating new pinned comment"
+          response=$(curl -s -w "%{http_code}" -X POST -H "Authorization: token ${GITHUB_TOKEN}" \
+            -H "Content-Type: application/json" \
+            -d "{\"body\":${ESCAPED_COMMENT}}" \
+            "https://api.github.com/repos/${GITHUB_REPOSITORY}/issues/${ISSUE_NUMBER}/comments")
+          status_code=${response: -3}
+
+          if [ "$status_code" != "201" ]; then
+            echo "Failed to create comment. Status code: ${status_code}"
+            exit 1
+          fi
+        fi

.github/workflows/docs_preview.yml

@@ -0,0 +1,117 @@
+name: Docs Preview
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.run_id }}
+  cancel-in-progress: true
+
+on:
+  pull_request_target:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - 'tools/github_readme_sync/**'
+      - '.github/workflows/docs_preview.yml'
+
+permissions:
+  pull-requests: write
+
+jobs:
+  deploy_docs_preview:
+    name: deploy-docs-preview
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout tbp.monty
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          lfs: true
+          path: tbp.monty
+
+      - name: Create initial PR comment
+        uses: ./tbp.monty/.github/actions/pin_comment
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          issue_number: ${{ github.event.pull_request.number }}
+          comment_id: docs-preview
+          working_directory: tbp.monty
+          message: |
+            📚 **Documentation Preview**
+
+            Building documentation preview... ⏳
+
+            Check the [workflow logs](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) for progress.
+      - name: Set up ~/tbp
+        run: |
+          mkdir -p ~/tbp
+          ln -s $GITHUB_WORKSPACE/tbp.monty ~/tbp/tbp.monty
+      - name: Set up Python 3.8
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.8"
+      - name: Install miniconda
+        run: |
+          if [ ! -d ~/miniconda ]
+          then
+            wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O ~/miniconda.sh
+            bash ~/miniconda.sh -b -p ~/miniconda
+            rm ~/miniconda.sh
+          fi
+          export PATH="$HOME/miniconda/bin:$PATH"
+          conda --version
+      - name: Create conda environment
+        working-directory: tbp.monty
+        run: |
+          export PATH="$HOME/miniconda/bin:$PATH"
+          (conda env list | grep tbp.monty) && conda remove --name tbp.monty --all --yes || true
+          conda env create
+          source activate tbp.monty
+          pip install -e .[dev,github_readme_sync_tool,print_version_tool]
+      - name: Get version and branch
+        working-directory: tbp.monty
+        run: |
+          export PATH="$HOME/miniconda/bin:$PATH"
+          source activate tbp.monty
+          echo "MONTY_VERSION=$(python -m tools.print_version.cli minor)" >> $GITHUB_ENV
+          # Make branch name safe for semver by replacing invalid chars with dash
+          # Remove trailing dash if present
+          echo "BRANCH_NAME=$(echo ${GITHUB_HEAD_REF} | tr -c '[:alnum:]' '-' | sed 's/-*$//')" >> $GITHUB_ENV
+          # Get current date in ISO format
+          echo "MONTY_DATE=$(date -u +'%Y-%m-%d %H:%M UTC')" >> $GITHUB_ENV
+      - name: Deploy docs
+        working-directory: tbp.monty
+        run: |
+          export PATH="$HOME/miniconda/bin:$PATH"
+          source activate tbp.monty
+          export README_API_KEY=${{ secrets.README_API_KEY }}
+          export IMAGE_PATH=${{ vars.IMAGE_PATH }}
+          python -m tools.github_readme_sync.cli upload docs "${MONTY_VERSION}-${BRANCH_NAME}"
+      - name: Update PR comment on success
+        if: success()
+        uses: ./tbp.monty/.github/actions/pin_comment
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          issue_number: ${{ github.event.pull_request.number }}
+          comment_id: docs-preview
+          working_directory: tbp.monty
+          message: |
+            📚 **Documentation Preview**
+
+            ✅ A preview of the documentation changes in this PR is available for maintainers at:
+            ${{ vars.DOCS_URL_PREFIX }}v${{ env.MONTY_VERSION }}-${{ env.BRANCH_NAME }}
+
+            Last updated: ${{ env.MONTY_DATE }}
+      - name: Update PR comment on failure
+        if: failure()
+        uses: ./tbp.monty/.github/actions/pin_comment
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          issue_number: ${{ github.event.pull_request.number }}
+          comment_id: docs-preview
+          working_directory: tbp.monty
+          message: |
+            📚 **Documentation Preview**
+
+            ❌ Failed to build documentation preview.
+
+            Check the [workflow logs](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) for details.