Workflow improvements

.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 "[email protected]"
- 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 "[email protected]";
+ 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