Add developer docs preview deployments (#679)

* Add developer docs preview deployments

* Add missing steps

* Remove unnecessary flags

* Make destination_dir relative

* Fix find comment string

.github/workflows/ci_cd.yml

@@ -158,17 +158,6 @@ jobs:
           name: api_logs
           path: api_logs
 
-      - name: Make developer docs
-        if: github.event_name == 'push' && github.repository == 'WordPress/openverse-api'
-        run: just sphinx-make
-
-      - name: Upload developer docs
-        if: github.event_name == 'push' && github.repository == 'WordPress/openverse-api'
-        uses: actions/upload-artifact@v2
-        with:
-          name: docs
-          path: api/build/html/
-
   django-check:
     name: Run Django check
     runs-on: ubuntu-latest
@@ -259,22 +248,112 @@ jobs:
             ghcr.io/wordpress/openverse-${{ matrix.image }}:${{ github.ref_name }}
           docker push --all-tags ghcr.io/wordpress/openverse-${{ matrix.image }}
 
-  docs:
+  publish-docs:
     name: Publish developer docs
     runs-on: ubuntu-latest
     if: github.event_name == 'push' && github.repository == 'WordPress/openverse-api'
     needs:
-      - test-api
+      - build-images
+
     steps:
-      - name: Download developer docs
+      - name: Checkout repository
+        uses: actions/checkout@v2
+
+      - name: Setup just
+        uses: extractions/setup-just@v1
+
+      - name: Download all images
         uses: actions/download-artifact@v2
         with:
-          name: docs
-          path: /tmp/docs
+          path: /tmp
+
+      - name: Load all images
+        run: |
+          docker load --input /tmp/api/api.tar
+          docker load --input /tmp/ingestion_server/ingestion_server.tar
+
+      - name: Make developer docs
+        run: just sphinx-make
 
       - name: Deploy
         uses: peaceiris/actions-gh-pages@bbdfb200618d235585ad98e965f4aafc39b4c501 # v3.7.3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: /tmp/docs
-          force_orphan: true
+          publish_dir: ./api/build/html/
+          keep_files: true
+
+  docs-preview:
+    name: Publish preview of developer docs for the branch
+    runs-on: ubuntu-latest
+    needs:
+      - build-images
+
+    steps:
+      - uses: peter-evans/find-comment@v2
+        id: preview-comment
+        with:
+          issue-number: ${{ github.event.pull_request.number }}
+          body-includes: API Developer Docs Preview
+
+      - uses: peter-evans/create-or-update-comment@v2
+        if: steps.preview-comment.outputs.comment-id != 0
+        with:
+          comment-id: ${{ steps.preview-comment.outputs.comment-id }}
+          edit-mode: replace
+          body: |
+            **API Developer Docs Preview**: _Updating_
+            (This comment will be automatically updated with the preview URL once it is ready)
+
+      - uses: peter-evans/create-or-update-comment@v2
+        if: steps.preview-comment.outputs.comment-id == 0
+        with:
+          issue-number: ${{ github.event.pull_request.number }}
+          body: |
+            **API Developer Docs Preview**: _Updating_
+            (This comment will be automatically updated with the preview URLs once it is ready)
+
+      - name: Checkout repository
+        uses: actions/checkout@v2
+
+      - name: Setup just
+        uses: extractions/setup-just@v1
+
+      - name: Download all images
+        uses: actions/download-artifact@v2
+        with:
+          path: /tmp
+
+      - name: Load all images
+        run: |
+          docker load --input /tmp/api/api.tar
+          docker load --input /tmp/ingestion_server/ingestion_server.tar
+
+      - name: Build docs
+        run: just sphinx-make
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./api/build/html/
+          destination_dir: _preview/${{ github.event.pull_request.number }}
+          keep_files: true
+
+      - uses: peter-evans/find-comment@v2
+        id: final-preview-comment
+        with:
+          issue-number: ${{ github.event.pull_request.number }}
+          body-includes: API Developer Docs Preview
+
+      - uses: peter-evans/create-or-update-comment@v2
+        with:
+          comment-id: ${{ steps.final-preview-comment.outputs.comment-id }}
+          edit-mode: replace
+          body: |
+            **API Developer Docs Preview**: _Ready_
+
+            <https://wordpress.github.io/openverse-api/_preview/${{ github.event.pull_request.number }}>
+
+            Please note that GitHub pages takes a little time to deploy newly pushed code, if the links above don't work or you see old versions, wait 5 minutes and try again.
+
+            You can check [the GitHub pages deployment action list](https://github.com/WordPress/openverse-api/actions/workflows/pages/pages-build-deployment) to see the current status of the deployments.

.github/workflows/pr_closed.yml

@@ -0,0 +1,26 @@
+name: PR Closed
+
+on:
+  pull_request:
+    types:
+      - closed
+
+jobs:
+  clean-gh-pages:
+    name: Clean API developer docs preview
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          ref: gh-pages
+
+      - name: Remove PR preview
+        run: rm -rf _preview/${{ github.event.pull_request.number }}
+
+      - name: Push cleaned branch
+        run: |
+          git config --global user.name 'PR Closed action'
+          git config --global user.email '[email protected]'
+          git commit -am 'Clean preview for PR ${{ github.event.pull_request.number }}'
+          git push