Workflow improvements

Author: lgarber-akamai

.github/workflows/publish-docs.yml

@@ -1,30 +1,16 @@
-name: Build and Publish Documentation
+name: Build Documentation
 
 on:
   push:
     branches:
-      - main
       - dev
-
-      # TODO: Remove this line
+      - main
       - new/doc-generation
-
+  pull_request:
   release:
     types:
       - published
 
-  workflow_dispatch:
-
-permissions:
-  contents: read
-  pages: write
-  id-token: write
-
-# Make sure we avoid a race condition =)
-concurrency:
-  group: "pages"
-  cancel-in-progress: false
-
 jobs:
   build:
     name: Build the documentation
@@ -50,12 +36,36 @@ jobs:
           pip install certifi -U && \
           pip install .[obj,dev]
 
+      - name: Resolve the target CLI version
+        uses: actions/github-script@v7
+        id: resolve-cli-version
+        with:
+          script: |
+            const latest_release = await github.rest.repos.getLatestRelease({
+              owner: context.repo.owner,
+              repo: context.repo.repo
+            });
+            
+            if (context.payload.release && latest_release.data.id == context.payload.release.id) {
+              let result = context.payload.release.tag_name;
+            
+              if (result.startsWith('v')) {
+                result = result.slice(1);
+              }
+            
+              return result;
+            }
+            
+            return '0.0.0.dev+' + context.sha.substring(0, 7);
+          result-encoding: string
+
       - name: Build the documentation
-        run: make generate-docs
+        run: make create-version && make generate-docs
         env:
           # We need to define a token to prevent the CLI from
           # attempting to do a first-time configuration.
           LINODE_CLI_TOKEN: foobar
+          LINODE_CLI_VERSION: ${{ steps.resolve-cli-version.outputs.result }}
 
       - name: Upload the artifact
         uses: actions/upload-artifact@v4
@@ -68,43 +78,60 @@ jobs:
     runs-on: ubuntu-latest
     needs:
       - build
+    # Make sure we avoid a race condition =)
+    concurrency:
+      group: "pages"
+      cancel-in-progress: false
+    permissions:
+      contents: write
+      pages: write
+      id-token: write
+    if: (github.event_name == 'push' && (github.ref_name == 'main' || github.ref_name == 'dev' || github.ref_name == 'new/doc-generation' )) || (github.ref_type == 'tag')
     steps:
-      - name: Checkout the GitHub Pages branch
+      - name: Checkout the documentation branch
+        continue-on-error: true
+        id: checkout-docs
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
           submodules: "recursive"
-          ref: "static/pages"
+          ref: "static/docs"
+
+      - name: Create the documentation branch if it does not already exist
+        if: "${{ steps.checkout-docs.outcome != 'success' }}"
+        run: git switch --orphan static/docs
 
       - name: Ensure any previous documentation for this branch are removed
-        run: rm -rf "./${{ github.ref }}"
+        run: rm -rf "./${{ github.ref_name }}"
 
       - name: Download the artifact from the previous job
         uses: actions/download-artifact@v4
         with:
           name: generated-docs-html
-          path: "${{ github.ref }}"
+          path: "${{ github.ref_name }}"
+
+      - name: Override the latest version if necessary
+        if: ${{ github.event_name == 'release' }}
+        run: |
+          rm -rf latest && cp -r ${{ github.ref_name }} latest
 
       - name: Commit and push this change
         run: |
-          git config user.name "Documentation Publisher"
-          git config user.email "dl-linode-dev-dx@akamai.com"
-          git add .
-          git commit -m "Rebuild ${{ github.ref }} from ${{ github.sha }}"
-          git push origin static/pages
-#
-#      # TODO: Implement some sort of page merging logic here so we can host
-#      #       separate pages for `dev`, `main` and commit hashes.
-#
-#      - name: Configure GitHub Pages
-#        uses: actions/configure-pages@v5
-#        with:
-#          enablement: true
-#
-#      - name: Push the rendered documentation site to GitHub Pages
-#        uses: actions/upload-pages-artifact@v3
-#        with:
-#          path: .docs-html
-#
-#      - name: Deploy to GitHub Pages
-#        uses: actions/deploy-pages@v4
+          git config user.name "Documentation Publisher";
+          git config user.email "dl-linode-dev-dx@akamai.com";
+          git add .;
+          git commit --allow-empty -m "Rebuild ${{ github.ref_name }} from ${{ github.sha }}";
+          git push origin static/docs;
+
+      - name: Configure GitHub Pages
+        uses: actions/configure-pages@v5
+        with:
+          enablement: true
+
+      - name: Push the rendered documentation site to GitHub Pages
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: .
+
+      - name: Deploy to GitHub Pages
+        uses: actions/deploy-pages@v4