develop → master

.github/workflows/deploy-typedoc.yml

@@ -0,0 +1,91 @@
+name: Build & Publish TypeDoc (master -> root, develop -> /develop)
+
+on:
+  push:
+    branches:
+      - develop
+      - master
+
+permissions:
+  contents: write
+
+jobs:
+  build-and-publish:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Use Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '18'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build TypeDoc (runs your 'docs' script)
+        run: npm run docs
+        # typedoc_html.json should output to ./html_docs
+
+      - name: Publish to gh-pages (master -> root, develop -> /develop)
+        env:
+          REPO: ${{ github.repository }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          BRANCH_NAME: ${{ github.ref_name }}
+        run: |
+          set -euo pipefail
+          echo "Publishing TypeDoc for branch: ${BRANCH_NAME}"
+
+          REMOTE="https://x-access-token:${GH_TOKEN}@github.com/${REPO}.git"
+          TMP=tmp-gh-pages
+          rm -rf "$TMP"
+          mkdir -p "$TMP"
+          cd "$TMP"
+
+          # If gh-pages exists on remote, clone it; otherwise init an empty repo and add remote
+          if git ls-remote --heads "${REMOTE}" gh-pages | grep -q 'refs/heads/gh-pages'; then
+            git clone --depth 1 --branch gh-pages "${REMOTE}" .
+          else
+            git init
+            git remote add origin "${REMOTE}"
+          fi
+
+          # Ensure .nojekyll is present
+          touch .nojekyll
+
+          # Publish logic:
+          # - If run on master => publish html_docs to root of gh-pages (overwrites root content but preserves /develop)
+          # - If run on develop => publish html_docs to gh-pages/develop/
+          if [ "${BRANCH_NAME}" = "master" ]; then
+            echo "Publishing master build to gh-pages root..."
+            # keep .git and /develop and .nojekyll - remove everything else from root
+            # enable extglob to use !(pattern)
+            bash -lc 'shopt -s extglob || true; rm -rf -- !(develop|.nojekyll|.git)'
+
+            # copy the built docs into the root
+            cp -r ../html_docs/* . || true
+          else
+            echo "Publishing develop build to gh-pages/develop/..."
+            rm -rf "${BRANCH_NAME}"
+            mkdir -p "${BRANCH_NAME}"
+            cp -r ../html_docs/* "${BRANCH_NAME}/" || true
+          fi
+
+          # Configure git user
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+          # Stage changes and commit
+          git add -A
+
+          if git rev-parse --verify HEAD >/dev/null 2>&1; then
+            git commit -m "chore(docs): update TypeDoc for ${BRANCH_NAME} (run: ${GITHUB_RUN_ID})" || echo "No changes to commit"
+          else
+            git commit -m "chore(docs): initialize gh-pages (run: ${GITHUB_RUN_ID})"
+          fi
+
+          # Push to gh-pages (creates branch if needed)
+          git push --force "${REMOTE}" HEAD:gh-pages

.gitignore

@@ -26,10 +26,13 @@ yarn-error.log*
 .DS_Store
 Thumbs.db
 
+*.tgz
+
 # IDE
 .idea/
 .vscode/
 *.swp
 *.swo
 
 /dist-tarballs
+html_docs/