diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index 911c08bdf..828ea8c9a 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -76,3 +76,35 @@ jobs: - run: npm publish --provenance --access public ${{ steps.npm-tag.outputs.tag }} env: NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} + + publish-gh-pages: + runs-on: ubuntu-latest + if: github.event_name == 'release' + needs: [publish] + + permissions: + contents: write + + steps: + - uses: actions/checkout@v4 + with: + fetch-depth: 0 # Fetch all history for all branches + + - uses: actions/setup-node@v4 + with: + node-version: 24 + cache: npm + + - name: Install dependencies + run: npm ci + + - name: Configure Git + run: | + git config --global user.name "github-actions[bot]" + git config --global user.email "github-actions[bot]@users.noreply.github.com" + + - name: Generate documentation + run: ./scripts/generate-gh-pages.sh ${{ github.ref_name }} + + - name: Push to gh-pages + run: git push origin gh-pages diff --git a/.prettierignore b/.prettierignore index ae37f91c7..713d4b0f1 100644 --- a/.prettierignore +++ b/.prettierignore @@ -11,3 +11,6 @@ pnpm-lock.yaml # Ignore generated files src/spec.types.ts + +# Jekyll/Liquid template files with special formatting requirements +docs/index.md diff --git a/README.md b/README.md index bcdf0d841..8e0a0cab9 100644 --- a/README.md +++ b/README.md @@ -1579,6 +1579,7 @@ app.listen(3000); ## Documentation +- [SDK API documentation](https://modelcontextprotocol.github.io/typescript-sdk/) - [Model Context Protocol documentation](https://modelcontextprotocol.io) - [MCP Specification](https://spec.modelcontextprotocol.io) - [Example Servers](https://github.com/modelcontextprotocol/servers) diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 000000000..67b2fb53c --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1,5 @@ +title: '@modelcontextprotocol/sdk' + +# Include generated files and directories which may start with underscores +include: + - '_*' diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 000000000..41cda449b --- /dev/null +++ b/docs/index.md @@ -0,0 +1,7 @@ +--- +# Empty Jekyll front matter to enable Liquid templating (see {{ ... }} below) +--- + +{% for version in site.data.versions %} +- [v{{ version }}](v{{ version }}/) +{% endfor %} diff --git a/docs/latest/index.html b/docs/latest/index.html new file mode 100644 index 000000000..983b4dcbe --- /dev/null +++ b/docs/latest/index.html @@ -0,0 +1,19 @@ +--- +# Empty Jekyll front matter to enable Liquid templating (see {{ ... }} below) +--- + + + + + + Redirecting to latest documentation... + + + + +

Redirecting to latest documentation...

+ + + diff --git a/package-lock.json b/package-lock.json index d6791ef06..e8693d78e 100644 --- a/package-lock.json +++ b/package-lock.json @@ -40,6 +40,7 @@ "prettier": "3.6.2", "supertest": "^7.0.0", "tsx": "^4.16.5", + "typedoc": "^0.28.14", "typescript": "^5.5.4", "typescript-eslint": "^8.0.0", "vitest": "^4.0.8", @@ -636,6 +637,20 @@ "node": "^18.18.0 || ^20.9.0 || >=21.1.0" } }, + "node_modules/@gerrit0/mini-shiki": { + "version": "3.15.0", + "resolved": "https://registry.npmjs.org/@gerrit0/mini-shiki/-/mini-shiki-3.15.0.tgz", + "integrity": "sha512-L5IHdZIDa4bG4yJaOzfasOH/o22MCesY0mx+n6VATbaiCtMeR59pdRqYk4bEiQkIHfxsHPNgdi7VJlZb2FhdMQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@shikijs/engine-oniguruma": "^3.15.0", + "@shikijs/langs": "^3.15.0", + "@shikijs/themes": "^3.15.0", + "@shikijs/types": "^3.15.0", + "@shikijs/vscode-textmate": "^10.0.2" + } + }, "node_modules/@humanfs/core": { "version": "0.19.0", "resolved": "https://registry.npmjs.org/@humanfs/core/-/core-0.19.0.tgz", @@ -1057,6 +1072,55 @@ "win32" ] }, + "node_modules/@shikijs/engine-oniguruma": { + "version": "3.15.0", + "resolved": "https://registry.npmjs.org/@shikijs/engine-oniguruma/-/engine-oniguruma-3.15.0.tgz", + "integrity": "sha512-HnqFsV11skAHvOArMZdLBZZApRSYS4LSztk2K3016Y9VCyZISnlYUYsL2hzlS7tPqKHvNqmI5JSUJZprXloMvA==", + "dev": true, + "license": "MIT", + "dependencies": { + "@shikijs/types": "3.15.0", + "@shikijs/vscode-textmate": "^10.0.2" + } + }, + "node_modules/@shikijs/langs": { + "version": "3.15.0", + "resolved": "https://registry.npmjs.org/@shikijs/langs/-/langs-3.15.0.tgz", + "integrity": "sha512-WpRvEFvkVvO65uKYW4Rzxs+IG0gToyM8SARQMtGGsH4GDMNZrr60qdggXrFOsdfOVssG/QQGEl3FnJ3EZ+8w8A==", + "dev": true, + "license": "MIT", + "dependencies": { + "@shikijs/types": "3.15.0" + } + }, + "node_modules/@shikijs/themes": { + "version": "3.15.0", + "resolved": "https://registry.npmjs.org/@shikijs/themes/-/themes-3.15.0.tgz", + "integrity": "sha512-8ow2zWb1IDvCKjYb0KiLNrK4offFdkfNVPXb1OZykpLCzRU6j+efkY+Y7VQjNlNFXonSw+4AOdGYtmqykDbRiQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@shikijs/types": "3.15.0" + } + }, + "node_modules/@shikijs/types": { + "version": "3.15.0", + "resolved": "https://registry.npmjs.org/@shikijs/types/-/types-3.15.0.tgz", + "integrity": "sha512-BnP+y/EQnhihgHy4oIAN+6FFtmfTekwOLsQbRw9hOKwqgNy8Bdsjq8B05oAt/ZgvIWWFrshV71ytOrlPfYjIJw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@shikijs/vscode-textmate": "^10.0.2", + "@types/hast": "^3.0.4" + } + }, + "node_modules/@shikijs/vscode-textmate": { + "version": "10.0.2", + "resolved": "https://registry.npmjs.org/@shikijs/vscode-textmate/-/vscode-textmate-10.0.2.tgz", + "integrity": "sha512-83yeghZ2xxin3Nj8z1NMd/NCuca+gsYXswywDy5bHvwlWL8tpTQmzGeUuHd9FC3E/SBEMvzJRwWEOz5gGes9Qg==", + "dev": true, + "license": "MIT" + }, "node_modules/@standard-schema/spec": { "version": "1.0.0", "resolved": "https://registry.npmjs.org/@standard-schema/spec/-/spec-1.0.0.tgz", @@ -1174,6 +1238,16 @@ "@types/send": "*" } }, + "node_modules/@types/hast": { + "version": "3.0.4", + "resolved": "https://registry.npmjs.org/@types/hast/-/hast-3.0.4.tgz", + "integrity": "sha512-WPs+bbQw5aCj+x6laNGWLH3wviHtoCv/P3+otBhbOhJgG8qtpdAMlTCxLtsTWA7LH1Oh/bFCHsBn0TPS5m30EQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/unist": "*" + } + }, "node_modules/@types/http-errors": { "version": "2.0.4", "resolved": "https://registry.npmjs.org/@types/http-errors/-/http-errors-2.0.4.tgz", @@ -1268,6 +1342,13 @@ "@types/superagent": "^8.1.0" } }, + "node_modules/@types/unist": { + "version": "3.0.3", + "resolved": "https://registry.npmjs.org/@types/unist/-/unist-3.0.3.tgz", + "integrity": "sha512-ko/gIFJRv177XgZsZcBwnqJN5x/Gien8qNOn0D5bQU/zAzVf9Zt3BlcUiLqhV9y4ARk0GbT3tnUiPNgnTXzc/Q==", + "dev": true, + "license": "MIT" + }, "node_modules/@types/ws": { "version": "8.5.12", "resolved": "https://registry.npmjs.org/@types/ws/-/ws-8.5.12.tgz", @@ -1315,6 +1396,7 @@ "resolved": "https://registry.npmjs.org/@typescript-eslint/parser/-/parser-8.11.0.tgz", "integrity": "sha512-lmt73NeHdy1Q/2ul295Qy3uninSqi6wQI18XwSpm8w0ZbQXUpjCAWP1Vlv/obudoBiIjJVjlztjQ+d/Md98Yxg==", "dev": true, + "peer": true, "dependencies": { "@typescript-eslint/scope-manager": "8.11.0", "@typescript-eslint/types": "8.11.0", @@ -1726,6 +1808,7 @@ "resolved": "https://registry.npmjs.org/acorn/-/acorn-8.14.0.tgz", "integrity": "sha512-cl669nCJTZBsL97OF4kUQm5g5hC2uihk0NxY3WENAC0TYdILVkAyHymAntgxGkl7K+t0cXIrH5siy5S4XkFycA==", "dev": true, + "peer": true, "bin": { "acorn": "bin/acorn" }, @@ -2163,6 +2246,19 @@ "node": ">= 0.8" } }, + "node_modules/entities": { + "version": "4.5.0", + "resolved": "https://registry.npmjs.org/entities/-/entities-4.5.0.tgz", + "integrity": "sha512-V0hjH4dGPh9Ao5p0MoRY6BVqtwCjhz6vI5LT8AJ55H+4g9/4vbHx1I54fS0XuclLhDHArPQCiMjDxjaL8fPxhw==", + "dev": true, + "license": "BSD-2-Clause", + "engines": { + "node": ">=0.12" + }, + "funding": { + "url": "https://github.com/fb55/entities?sponsor=1" + } + }, "node_modules/es-define-property": { "version": "1.0.1", "resolved": "https://registry.npmjs.org/es-define-property/-/es-define-property-1.0.1.tgz", @@ -2280,6 +2376,7 @@ "resolved": "https://registry.npmjs.org/eslint/-/eslint-9.13.0.tgz", "integrity": "sha512-EYZK6SX6zjFHST/HRytOdA/zE72Cq/bfw45LSyuwrdvcclb/gqV8RRQxywOBEWO2+WDpva6UZa4CcDeJKzUCFA==", "dev": true, + "peer": true, "dependencies": { "@eslint-community/eslint-utils": "^4.2.0", "@eslint-community/regexpp": "^4.11.0", @@ -3184,6 +3281,16 @@ "node": ">= 0.8.0" } }, + "node_modules/linkify-it": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/linkify-it/-/linkify-it-5.0.0.tgz", + "integrity": "sha512-5aHCbzQRADcdP+ATqnDuhhJ/MRIqDkZX5pyjFHRRysS8vZ5AbqGEoFIb6pYHPZ+L/OC2Lc+xT8uHVVR5CAK/wQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "uc.micro": "^2.0.0" + } + }, "node_modules/locate-path": { "version": "6.0.0", "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-6.0.0.tgz", @@ -3205,6 +3312,13 @@ "integrity": "sha512-0KpjqXRVvrYyCsX1swR/XTK0va6VQkQM6MNo7PqW77ByjAhoARA8EfrP1N4+KlKj8YS0ZUCtRT/YUuhyYDujIQ==", "dev": true }, + "node_modules/lunr": { + "version": "2.3.9", + "resolved": "https://registry.npmjs.org/lunr/-/lunr-2.3.9.tgz", + "integrity": "sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow==", + "dev": true, + "license": "MIT" + }, "node_modules/magic-string": { "version": "0.30.21", "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.30.21.tgz", @@ -3215,6 +3329,24 @@ "@jridgewell/sourcemap-codec": "^1.5.5" } }, + "node_modules/markdown-it": { + "version": "14.1.0", + "resolved": "https://registry.npmjs.org/markdown-it/-/markdown-it-14.1.0.tgz", + "integrity": "sha512-a54IwgWPaeBCAAsv13YgmALOF1elABB08FxO9i+r4VFk5Vl4pKokRPeX8u5TCgSsPi6ec1otfLjdOpVcgbpshg==", + "dev": true, + "license": "MIT", + "dependencies": { + "argparse": "^2.0.1", + "entities": "^4.4.0", + "linkify-it": "^5.0.0", + "mdurl": "^2.0.0", + "punycode.js": "^2.3.1", + "uc.micro": "^2.1.0" + }, + "bin": { + "markdown-it": "bin/markdown-it.mjs" + } + }, "node_modules/math-intrinsics": { "version": "1.1.0", "resolved": "https://registry.npmjs.org/math-intrinsics/-/math-intrinsics-1.1.0.tgz", @@ -3224,6 +3356,13 @@ "node": ">= 0.4" } }, + "node_modules/mdurl": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/mdurl/-/mdurl-2.0.0.tgz", + "integrity": "sha512-Lf+9+2r+Tdp5wXDXC4PcIBjTDtq4UKjCPMQhKIuzpJNW0b96kVqSwW0bT7FhRSfmAiFYgP+SCRvdrDozfh0U5w==", + "dev": true, + "license": "MIT" + }, "node_modules/media-typer": { "version": "1.1.0", "resolved": "https://registry.npmjs.org/media-typer/-/media-typer-1.1.0.tgz", @@ -3605,6 +3744,16 @@ "node": ">=6" } }, + "node_modules/punycode.js": { + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/punycode.js/-/punycode.js-2.3.1.tgz", + "integrity": "sha512-uxFIHU0YlHYhDQtV4R9J6a52SLx28BCjT+4ieh7IGbgwVJWO+km431c4yRlREUAsAmt/uMjQUyQHNEPf0M39CA==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=6" + } + }, "node_modules/qs": { "version": "6.13.0", "resolved": "https://registry.npmjs.org/qs/-/qs-6.13.0.tgz", @@ -4138,6 +4287,7 @@ "integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==", "dev": true, "license": "MIT", + "peer": true, "engines": { "node": ">=12" }, @@ -4193,6 +4343,7 @@ "integrity": "sha512-4H8vUNGNjQ4V2EOoGw005+c+dGuPSnhpPBPHBtsZdGZBk/iJb4kguGlPWaZTZ3q5nMtFOEsY0nRDlh9PJyd6SQ==", "dev": true, "license": "MIT", + "peer": true, "dependencies": { "esbuild": "~0.25.0", "get-tsconfig": "^4.7.5" @@ -4233,11 +4384,62 @@ "node": ">= 0.6" } }, + "node_modules/typedoc": { + "version": "0.28.14", + "resolved": "https://registry.npmjs.org/typedoc/-/typedoc-0.28.14.tgz", + "integrity": "sha512-ftJYPvpVfQvFzpkoSfHLkJybdA/geDJ8BGQt/ZnkkhnBYoYW6lBgPQXu6vqLxO4X75dA55hX8Af847H5KXlEFA==", + "dev": true, + "license": "Apache-2.0", + "dependencies": { + "@gerrit0/mini-shiki": "^3.12.0", + "lunr": "^2.3.9", + "markdown-it": "^14.1.0", + "minimatch": "^9.0.5", + "yaml": "^2.8.1" + }, + "bin": { + "typedoc": "bin/typedoc" + }, + "engines": { + "node": ">= 18", + "pnpm": ">= 10" + }, + "peerDependencies": { + "typescript": "5.0.x || 5.1.x || 5.2.x || 5.3.x || 5.4.x || 5.5.x || 5.6.x || 5.7.x || 5.8.x || 5.9.x" + } + }, + "node_modules/typedoc/node_modules/brace-expansion": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.2.tgz", + "integrity": "sha512-Jt0vHyM+jmUBqojB7E1NIYadt0vI0Qxjxd2TErW94wDz+E2LAm5vKMXXwg6ZZBTHPuUlDgQHKXvjGBdfcF1ZDQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "balanced-match": "^1.0.0" + } + }, + "node_modules/typedoc/node_modules/minimatch": { + "version": "9.0.5", + "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.5.tgz", + "integrity": "sha512-G6T0ZX48xgozx7587koeX9Ys2NYy6Gmv//P89sEte9V9whIapMNF4idKxnW2QtCcLiTWlb/wfCabAtAFWhhBow==", + "dev": true, + "license": "ISC", + "dependencies": { + "brace-expansion": "^2.0.1" + }, + "engines": { + "node": ">=16 || 14 >=14.17" + }, + "funding": { + "url": "https://github.com/sponsors/isaacs" + } + }, "node_modules/typescript": { "version": "5.6.3", "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.6.3.tgz", "integrity": "sha512-hjcS1mhfuyi4WW8IWtjP7brDrG2cuDZukyrYrSauoXGNgx0S7zceP07adYkJycEr56BOUTNPzbInooiN3fn1qw==", "dev": true, + "peer": true, "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" @@ -4269,6 +4471,13 @@ } } }, + "node_modules/uc.micro": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/uc.micro/-/uc.micro-2.1.0.tgz", + "integrity": "sha512-ARDJmphmdvUk6Glw7y9DQ2bFkKBHwQHLi2lsaH6PPmz/Ka9sFOBsBluozhDltWmnv9u/cF6Rt87znRTPV+yp/A==", + "dev": true, + "license": "MIT" + }, "node_modules/undici-types": { "version": "6.21.0", "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz", @@ -4439,6 +4648,7 @@ "integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==", "dev": true, "license": "MIT", + "peer": true, "engines": { "node": ">=12" }, @@ -4452,6 +4662,7 @@ "integrity": "sha512-BxAKBWmIbrDgrokdGZH1IgkIk/5mMHDreLDmCJ0qpyJaAteP8NvMhkwr/ZCQNqNH97bw/dANTE9PDzqwJghfMQ==", "dev": true, "license": "MIT", + "peer": true, "dependencies": { "esbuild": "^0.25.0", "fdir": "^6.5.0", @@ -4587,6 +4798,19 @@ } } }, + "node_modules/yaml": { + "version": "2.8.1", + "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.8.1.tgz", + "integrity": "sha512-lcYcMxX2PO9XMGvAJkJ3OsNMw+/7FKes7/hgerGUYWIoWu5j/+YQqcZr5JnPZWzOsEBgMbSbiSTn/dv/69Mkpw==", + "dev": true, + "license": "ISC", + "bin": { + "yaml": "bin.mjs" + }, + "engines": { + "node": ">= 14.6" + } + }, "node_modules/yocto-queue": { "version": "0.1.0", "resolved": "https://registry.npmjs.org/yocto-queue/-/yocto-queue-0.1.0.tgz", @@ -4604,6 +4828,7 @@ "resolved": "https://registry.npmjs.org/zod/-/zod-3.25.76.tgz", "integrity": "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==", "license": "MIT", + "peer": true, "funding": { "url": "https://github.com/sponsors/colinhacks" } diff --git a/package.json b/package.json index 560c4bcb2..4a0c06caf 100644 --- a/package.json +++ b/package.json @@ -70,7 +70,7 @@ "prepack": "npm run build:esm && npm run build:cjs", "lint": "eslint src/ && prettier --check .", "lint:fix": "eslint src/ --fix && prettier --write .", - "check": "npm run typecheck && npm run lint", + "check": "npm run typecheck && npm run lint && npm exec typedoc -- --emit none", "test": "vitest run", "test:watch": "vitest", "start": "npm run server", @@ -121,6 +121,7 @@ "prettier": "3.6.2", "supertest": "^7.0.0", "tsx": "^4.16.5", + "typedoc": "^0.28.14", "typescript": "^5.5.4", "typescript-eslint": "^8.0.0", "vitest": "^4.0.8", diff --git a/scripts/generate-gh-pages.sh b/scripts/generate-gh-pages.sh new file mode 100755 index 000000000..7cf995c9c --- /dev/null +++ b/scripts/generate-gh-pages.sh @@ -0,0 +1,136 @@ +#!/bin/bash +set -e + +# Generates versioned API documentation and commits to gh-pages branch +# +# PURPOSE: +# This script generates API documentation in the gh-pages branch for a +# specific version tag while preserving existing versioned documentation. +# This script is invoked by the publish-gh-pages job in the GitHub Actions +# workflow (.github/workflows/main.yml) when a release is published. +# +# HOW IT WORKS: +# - Creates isolated git worktrees for the specified tag and gh-pages branch +# - Generates documentation into gh-pages in a directory based on the tag name (e.g., v1.2.3/) +# - Copies static Jekyll template files from docs/ +# - Generates _data/versions.yml with list of versions +# - Commits changes to gh-pages (does not push automatically) +# +# WORKFLOW: +# 1. Run this script with a tag name: `generate-gh-pages.sh v1.2.3` +# 2. Script generates docs and commits to local gh-pages branch +# 3. Push gh-pages branch to deploy: `git push origin gh-pages` + +# Parse semantic version from tag name (ignoring arbitrary prefixes) +if [[ "${1}" =~ ([0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.-]+)?)$ ]]; then + VERSION="v${BASH_REMATCH[1]}" +else + echo "Error: Must specify a tag name that contains a valid semantic version" + echo "Usage: ${0} " + echo "Examples:" + echo " ${0} 1.2.3" + echo " ${0} v2.0.0-rc.1" + exit 1 +fi + +TAG_NAME="${1}" +REPO_ROOT="$(git rev-parse --show-toplevel)" + +echo "Generating documentation for tag: ${TAG_NAME}" + +# Create temporary directories for both worktrees +WORKTREE_DIR=$(mktemp -d) +GHPAGES_WORKTREE_DIR=$(mktemp -d) + +# Set up trap to clean up both worktrees on exit +trap 'git worktree remove --force "${WORKTREE_DIR}" 2>/dev/null || true; \ + git worktree remove --force "${GHPAGES_WORKTREE_DIR}" 2>/dev/null || true' EXIT + +echo "Creating worktree for ${TAG_NAME}..." +git worktree add --quiet "${WORKTREE_DIR}" "${TAG_NAME}" + +# Check if gh-pages branch exists +if git show-ref --verify --quiet refs/heads/gh-pages; then + echo "Creating worktree for existing gh-pages branch..." + git worktree add --quiet "${GHPAGES_WORKTREE_DIR}" gh-pages +elif git ls-remote --exit-code --heads origin gh-pages > /dev/null 2>&1; then + echo "Creating worktree for gh-pages branch from remote..." + git worktree add --quiet "${GHPAGES_WORKTREE_DIR}" -b gh-pages origin/gh-pages +else + echo "Creating worktree for new orphan gh-pages branch..." + git worktree add --quiet --detach "${GHPAGES_WORKTREE_DIR}" + git -C "${GHPAGES_WORKTREE_DIR}" checkout --orphan gh-pages + git -C "${GHPAGES_WORKTREE_DIR}" rm -rf . > /dev/null 2>&1 || true +fi + +# Generate TypeDoc documentation into gh-pages worktree +cd "${WORKTREE_DIR}" +echo "Installing dependencies..." +npm ci --ignore-scripts + +# Support generating documentation for older tags +npm install --no-save typedoc +cp -n "${REPO_ROOT}/typedoc.json" "${REPO_ROOT}/tsconfig.prod.json" . 2>/dev/null || true + +# Create target directory for docs +echo "Creating versioned directory: ${VERSION}" +mkdir -p "${GHPAGES_WORKTREE_DIR}/${VERSION}" + +echo "Generating TypeDoc documentation..." +npx typedoc --out "${GHPAGES_WORKTREE_DIR}/${VERSION}" +cd "${REPO_ROOT}" + +# Ensure docs were generated +if [ -z "$(ls -A "${GHPAGES_WORKTREE_DIR}/${VERSION}")" ]; then + echo "Error: Documentation was not generated at ${GHPAGES_WORKTREE_DIR}/${VERSION}" + exit 1 +fi + +# Change to gh-pages worktree +cd "${GHPAGES_WORKTREE_DIR}" + +# Determine if this tag is the latest version +echo "Determining if ${VERSION} is the latest version..." + +# Get the latest version from all version directories (excluding 'latest') +LATEST_VERSION=$(printf '%s\n' */ | grep '^v[0-9]' | sed 's:/$::' | sort -V | tail -n 1) + +if [ "${VERSION}" = "${LATEST_VERSION}" ]; then + echo "${VERSION} is the latest version" +else + echo "${VERSION} is not the latest version (latest is ${LATEST_VERSION})" +fi + +# Update custom documentation for latest version +if [ "${VERSION}" = "${LATEST_VERSION}" ]; then + echo "Updating custom documentation..." + + # Clean up old custom docs from gh-pages root (keep only version directories) + echo "Cleaning gh-pages root..." + git ls-tree --name-only HEAD | grep -v '^v[0-9]' | xargs -r git rm -rf + + # Copy custom docs from docs/ directory + echo "Copying custom docs from ${WORKTREE_DIR}/docs/..." + cp -r "${WORKTREE_DIR}/docs/." "${GHPAGES_WORKTREE_DIR}/" +fi + +# Generate version data for Jekyll +echo "Generating _data/versions.yml..." +mkdir -p _data +printf '%s\n' */ | grep '^v[0-9]' | sed -e 's/^v//' -e 's:/$::' | sort -Vr | sed 's/^/- /' > _data/versions.yml + +# Stage all changes +git add . + +# Commit if there are changes +if git diff --staged --quiet; then + echo "No changes to commit" +else + echo "Committing documentation for ${VERSION}..." + git commit -m "Add ${VERSION} docs" + + echo "Documentation committed to gh-pages branch!" + echo "Push to remote to deploy to GitHub Pages" +fi + +echo "Done!" diff --git a/typedoc.json b/typedoc.json new file mode 100644 index 000000000..b79c77a27 --- /dev/null +++ b/typedoc.json @@ -0,0 +1,6 @@ +{ + "$schema": "https://typedoc.org/schema.json", + "entryPoints": ["src"], + "entryPointStrategy": "expand", + "tsconfig": "tsconfig.prod.json" +}