ci: improve the release docs workflow

old docs will now be handled correctly

.github/workflows/release-docs.yml

@@ -14,49 +14,42 @@ concurrency:
   cancel-in-progress: false
 
 jobs:
-  get_old_docs:
+  update_and_deploy_docs:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
     steps:
-      - name: get the gh-pages repo
+      - name: get the current docs
         uses: actions/checkout@v3
         with:
           ref: gh-pages
-        continue-on-error: true
 
-      - name: tar the existing docs
-        run: |
-          mkdir -p ./docs/generated
-          tar -cvf old-docs.tar ./docs/generated
+      - name: Save old docs
+        run: tar -cvf /tmp/old-docs.tar ./docs/generated
 
-      - name: create a document artifact
-        uses: actions/upload-artifact@v3
-        with:
-          name: old-docs
-          path: old-docs.tar
-
-  update_and_deploy_docs:
-    needs: get_old_docs
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    runs-on: ubuntu-latest
-    steps:
       - name: Checkout src
         uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+          clean: false #  doesn't seem to work?? - Hence use of tarballs
 
-      - uses: ./.github/actions/prepare
+      - name: Restore old docs
+        run: |
+          mkdir -p ./docs/generated
+          tar -xf /tmp/old-docs.tar ./docs/generated -C ./docs/generated
 
-      - run: mkdir -p ./docs/generated
-      - name: Download the existing documents artifact
-        uses: actions/download-artifact@v3
-        with:
-          name: old-docs
+      - uses: ./.github/actions/prepare
 
-      - run: tar -xf old-docs.tar ./docs/generated -C ./docs/generated
+      - name: Build
+        run: pnpm run build
 
       - name: Build docs
         run: pnpm run docs
 
+      - name: Save new docs
+        run: tar -cvf /tmp/new-docs.tar ./docs/generated
+
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v2
         with:
@@ -67,6 +60,7 @@ jobs:
         uses: actions/deploy-pages@v2
 
       - run: 'echo "PACKAGE_VERSION=$(cat package.json | grep version | head -1 | awk -F: ''{ print $2 }'' | sed ''s/[", ]//g'')" >> $GITHUB_ENV'
+
       - name: Update Coverage Badge
         run: cp ./docs/generated/v$PACKAGE_VERSION/coverage.svg ./docs/coverage.svg
 
@@ -87,10 +81,32 @@ jobs:
       - if: steps.push_coverage.outputs.push_coverage != '0'
         run: |
           git add docs/coverage.svg
-          git commit -m "docs: updated documentation coverage"
+          git commit -m "docs: update documentation coverage"
           git push
 
       - if: ${{ always() && steps.push_coverage.outputs.push_coverage != '0' }}
         uses: ./.github/actions/protect-main
         with:
           ACCESS_TOKEN: ${{ secrets.ACCESS_TOKEN }}
+
+      - name: get gh-pages
+        uses: actions/checkout@v3
+        with:
+          ref: gh-pages
+          clean: false #  doesn't seem to work?? - Hence use of tarballs
+
+      - name: Restore new docs
+        run: |
+          rm -r ./docs/generated
+          mkdir -p ./docs/generated
+          tar -xf /tmp/new-docs.tar ./docs/generated -C ./docs/generated
+
+      - name: Push new docs
+        run: |
+          git add -f docs/generated
+          git commit -m "docs: update documentation"
+          git push
+        continue-on-error: true
+
+      - name: Checkout src
+        uses: actions/checkout@v3

package.json

@@ -28,7 +28,9 @@
 	],
 	"scripts": {
 		"build": "tsup src/index.ts --clean --format cjs,esm --outDir lib --dts && cp lib/index.d.ts lib/index.d.cts",
-		"docs": "typedoc",
+		"docs": "pnpm run docs:build && pnpm run docs:build-post",
+		"docs:build": "typedoc",
+		"docs:build-post": "find -lname \"$PWD/docs/generated/*\" | while read link; do target=$(readlink $link); relative_target=$(realpath $target --relative-to=$link/.. --no-symlinks --canonicalize-missing); ln --force --symbolic --no-target-directory $relative_target $link; done",
 		"docs:serve": "http-serve docs/generated",
 		"format": "prettier \"**/*\" --ignore-unknown",
 		"format:write": "pnpm format --write",