ci: use custom PR message action

.github/workflows/docs.yml

@@ -78,7 +78,7 @@ jobs:
       with:
         name: awkward-x86-64-wheel
         path: dist/awkward*.whl
-  docs:
+  build-docs:
     runs-on: ubuntu-22.04
     needs: [awkward-wasm, awkward-x86-64]
     steps:
@@ -116,10 +116,37 @@ jobs:
       with:
         name: jupyter-cache
         path: docs-sphinx/_build/.jupyter_cache
-    - name: Trigger RTD Build
-      env:
-          RTD_TOKEN: "${{ secrets.RTD_TOKEN }}"
+  deploy-docs:
+    runs-on: ubuntu-22.04
+    needs: [build-docs]
+    # We can only deploy for PRs on host repo
+    if: github.event.pull_request.head.repo.full_name == github.repository
+    steps:
+    - uses: actions/checkout@v3
+    - name: Activate RTD version
       run: |
+        # Sanitise ref name
         # NB: head_ref is only valid for PR triggers
-        python3 dev/activate-docs-version.py "${{ github.head_ref || github.ref_name }}"
-        python3 dev/trigger-docs-build.py "${{ github.head_ref || github.ref_name }}"
+        export VERSION_SLUG=$(echo "${{ github.head_ref || github.ref_name }}" | sed -E "s@[_/]@-@")
+        # Export for subsequent steps
+        echo "VERSION_SLUG=$VERSION_SLUG" >> $GITHUB_ENV
+        # Activate version
+        curl \
+          -X PATCH \
+          -H "Authorization: Token ${{ secrets.RTD_TOKEN }}" \
+              "https://readthedocs.org/api/v3/projects/awkward-array/versions/$VERSION_SLUG/" \
+          -H "Content-Type: application/json" \
+          -d '{"active":true,"hidden":true}'
+    - name: Trigger RTD build
+      run: |
+        # Trigger build
+        curl \
+          -X POST \
+          -H "Authorization: Token ${{ secrets.RTD_TOKEN }}" \
+              "https://readthedocs.org/api/v3/projects/awkward-array/versions/$VERSION_SLUG/builds/"
+    - name: Edit PR description
+      uses: actions/github-script@v6
+      with:
+        script: |
+            const script = require('./dev/docs-edit-message.js');
+            console.log(script(github, context, "${{ env.VERSION_SLUG }}"));

dev/docs-edit-message.js

@@ -0,0 +1,31 @@
+async function update_pr_description(github, context, version_slug) {
+
+    const {data: pull} = await github.rest.pulls.get({
+        owner: context.repo.owner,
+        repo: context.repo.repo,
+        pull_number: context.issue.number,
+    });
+    const MESSAGE_START = `<!-- docs-preview-start -->`;
+    const MESSAGE_END = `<!-- docs-preview-end -->`;
+    const MESSAGE_BODY = `----\n:books: The documentation for this PR will be available at <https://awkward-array.readthedocs.io/en/${version_slug}/> once Read the Docs has finished building :hammer:`;
+    const MESSAGE = `\r\n\r\n${MESSAGE_START}\r\n${MESSAGE_BODY}\r\n${MESSAGE_END}`
+
+    // Only include message if this is the first time.
+    let body = "";
+    if (!pull.body) {
+        body = MESSAGE;
+    } else if (pull.body.indexOf(MESSAGE_START) === -1) {
+        body = pull.body + MESSAGE;
+    } else {
+        return;
+    }
+    // Update description
+    github.rest.pulls.update({
+        owner: context.repo.owner,
+        repo: context.repo.repo,
+        pull_number: context.issue.number,
+        body: body,
+    });
+}
+
+module.exports = update_pr_description;