From b8eeb5dcefc947411f446679f961ea5987211848 Mon Sep 17 00:00:00 2001 From: Jonathan Hefner Date: Thu, 27 Nov 2025 14:36:49 -0600 Subject: [PATCH] Add API documentation with GitHub Pages deployment This adds automated generation and deployment of versioned API documentation using TypeDoc and GitHub Pages. Documentation will be generated and published when a new release is created. Changes ------- 1. **Documentation generation script** (see `scripts/generate-gh-pages.sh`) Generates TypeDoc documentation for a specific version tag and commits it to the gh-pages branch. The script uses git worktrees to isolate the documentation generation process from the main workspace. Documentation for each release is stored in a versioned directory (e.g., `v1.2.3/`) on the gh-pages branch. The script: - Parses semantic versions from tag names, ignoring arbitrary prefixes (e.g., tags `1.2.3`, `v1.2.3`, and `release-1.2.3` all create `v1.2.3/`) - Creates the gh-pages branch as an orphan branch if it doesn't exist - Generates new doc pages while preserving existing versioned directories - Generates `_data/latest_version.yml` for Jekyll template - Determines the latest version via semantic version sorting - For the latest version only, copies static Jekyll template files from `.github/pages/` to the gh-pages root 2. **Jekyll template files** (see `.github/pages/` directory) - `.github/pages/_config.yml` - Jekyll configuration - `.github/pages/index.html` - Landing page that redirects to the latest version based on the generated `_data/latest_version.yml` 3. **GitHub Actions workflow** (see `.github/workflows/main.yml`) Added a `publish-gh-pages` job that runs after the `publish` job on release events. This ensures documentation is generated and published only after the npm package is successfully published. The job invokes the generation script with the release tag name and pushes the updated gh-pages branch. 4. **CI validation** (see `package.json`) Updated the `check` script to include TypeDoc validation with `--emit none`. This ensures TypeDoc can successfully parse the codebase (without generating output), catching documentation issues early in CI. 5. **Documentation link** (see `README.md`) Added a link to the published API documentation in the Documentation section of the README. TypeDoc Configuration --------------------- TypeDoc is configured via `typedoc.json`: - Uses the `src` directory as the entry point with the `expand` strategy - Explicitly excludes test files, mocks, examples, and integration tests Documentation URL ----------------- Documentation will be available at: https://modelcontextprotocol.github.io/typescript-sdk/ Versioned API documentation will be available at: - https://modelcontextprotocol.github.io/typescript-sdk/ (redirects to latest) - https://modelcontextprotocol.github.io/typescript-sdk/v1.2.3/ (specific versions) Co-Authored-By: Claude latest version --- .github/pages/_config.yml | 5 + .github/pages/index.html | 19 +++ .github/workflows/main.yml | 32 ++++++ README.md | 1 + package-lock.json | 216 +++++++++++++++++++++++++++++++++++ package.json | 3 +- scripts/generate-gh-pages.sh | 123 ++++++++++++++++++++ typedoc.json | 6 + 8 files changed, 404 insertions(+), 1 deletion(-) create mode 100644 .github/pages/_config.yml create mode 100644 .github/pages/index.html create mode 100755 scripts/generate-gh-pages.sh create mode 100644 typedoc.json diff --git a/.github/pages/_config.yml b/.github/pages/_config.yml new file mode 100644 index 000000000..67b2fb53c --- /dev/null +++ b/.github/pages/_config.yml @@ -0,0 +1,5 @@ +title: '@modelcontextprotocol/sdk' + +# Include generated files and directories which may start with underscores +include: + - '_*' diff --git a/.github/pages/index.html b/.github/pages/index.html new file mode 100644 index 000000000..d9bb388cc --- /dev/null +++ b/.github/pages/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/.github/workflows/main.yml b/.github/workflows/main.yml index 60144add1..824e3daf6 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -87,3 +87,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/README.md b/README.md index e0d3f200f..68f526c8b 100644 --- a/README.md +++ b/README.md @@ -156,6 +156,7 @@ For more details on how to run these examples (including recommended commands an - [docs/capabilities.md](docs/capabilities.md) – sampling, elicitation (form and URL), and experimental task-based execution. - [docs/faq.md](docs/faq.md) – environment and troubleshooting FAQs (including Node.js Web Crypto support). - External references: + - [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/package-lock.json b/package-lock.json index d32963a73..3cd89efbb 100644 --- a/package-lock.json +++ b/package-lock.json @@ -44,6 +44,7 @@ "prettier": "3.6.2", "supertest": "^7.0.0", "tsx": "^4.16.5", + "typedoc": "^0.28.14", "typescript": "^5.5.4", "typescript-eslint": "^8.48.1", "vitest": "^4.0.8", @@ -663,6 +664,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.1", "resolved": "https://registry.npmjs.org/@humanfs/core/-/core-0.19.1.tgz", @@ -1052,6 +1067,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", @@ -1169,6 +1233,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", @@ -1264,6 +1338,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", @@ -2176,6 +2257,19 @@ "node": ">=10.13.0" } }, + "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", @@ -3211,6 +3305,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", @@ -3232,6 +3336,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", @@ -3242,6 +3353,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", @@ -3251,6 +3380,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", @@ -3606,6 +3742,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.14.0", "resolved": "https://registry.npmjs.org/qs/-/qs-6.14.0.tgz", @@ -4193,6 +4339,56 @@ "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", @@ -4231,6 +4427,13 @@ "typescript": ">=4.8.4 <6.0.0" } }, + "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", @@ -4543,6 +4746,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", diff --git a/package.json b/package.json index bfbc73802..eb14c1335 100644 --- a/package.json +++ b/package.json @@ -78,7 +78,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", @@ -133,6 +133,7 @@ "prettier": "3.6.2", "supertest": "^7.0.0", "tsx": "^4.16.5", + "typedoc": "^0.28.14", "typescript": "^5.5.4", "typescript-eslint": "^8.48.1", "vitest": "^4.0.8", diff --git a/scripts/generate-gh-pages.sh b/scripts/generate-gh-pages.sh new file mode 100755 index 000000000..88be85cb6 --- /dev/null +++ b/scripts/generate-gh-pages.sh @@ -0,0 +1,123 @@ +#!/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 .github/pages/ +# - 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` + +TAG_NAME="${1}" + +# Parse semantic version from tag name (ignoring arbitrary prefixes) +if [[ "${TAG_NAME}" =~ ([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 + +echo "Generating documentation for tag: ${TAG_NAME}" + +# Generates documentation for the given source directory. +# +# Can modify this function to customize documentation structure. +# For example, to add guides from ./docs/ and nest API docs under /api: +# 1. Copy docs/ contents: `cp -r docs/* "${output_dir}/"` +# 2. Change typedoc output: `npx typedoc --out "${output_dir}/api"` +generate_docs() { + local source_dir="${1}" + local output_dir="${2}" + + # Resolve to absolute path (because typedoc runs from source_dir) + [[ "${output_dir}" != /* ]] && output_dir="$(pwd)/${output_dir}" + + echo "Installing dependencies..." + (cd "${source_dir}" && npm ci --ignore-scripts) + + echo "Generating TypeDoc documentation..." + (cd "${source_dir}" && npx typedoc --out "${output_dir}") + + # Verify docs were generated + if [ -z "$(ls -A "${output_dir}")" ]; then + echo "Error: Documentation was not generated at ${output_dir}" + exit 1 + fi +} + +# Create temporary directories for both worktrees +TAG_WORKTREE_DIR=$(mktemp -d) +GHPAGES_WORKTREE_DIR=$(mktemp -d) + +# Set up trap to clean up both worktrees on exit +trap 'git worktree remove --force "${TAG_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 "${TAG_WORKTREE_DIR}" "${TAG_NAME}" + +# Fetch gh-pages from remote if available (creates local branch if missing) +git fetch --quiet origin gh-pages:refs/heads/gh-pages 2>/dev/null || true + +if git show-ref --verify --quiet refs/heads/gh-pages; then + echo "Creating worktree for gh-pages branch..." + git worktree add --quiet "${GHPAGES_WORKTREE_DIR}" 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}" switch --orphan gh-pages +fi + +# Change to gh-pages worktree for all subsequent operations +cd "${GHPAGES_WORKTREE_DIR}" + +# Generate TypeDoc documentation into gh-pages worktree +mkdir -p "${VERSION}" +generate_docs "${TAG_WORKTREE_DIR}" "${VERSION}" + +# Generate version data for Jekyll +echo "Generating _data/latest_version.yml..." +mkdir -p _data +LATEST_VERSION="v$(printf '%s\n' */ | grep '^v[0-9]' | sed -e 's/^v//' -e 's:/$::' | sort -Vr | head -1)" +echo "${LATEST_VERSION}" > _data/latest_version.yml + +if [ "${VERSION}" = "${LATEST_VERSION}" ]; then + echo "${VERSION} is the latest version, updating static files..." + + # Clean up old tracked files from gh-pages root (but preserve directories) + git ls-files -z | grep -zv '/' | xargs -0 rm -f + + # Copy static files from .github/pages/ + find "${TAG_WORKTREE_DIR}/.github/pages" -maxdepth 1 -type f -exec cp -t . {} + +else + echo "${VERSION} is not the latest version (latest is ${LATEST_VERSION})" +fi + +# Commit if there are changes +git add . + +if git diff --staged --quiet; then + echo "No changes to commit for tag ${TAG_NAME}" +else + git commit -m "Add ${VERSION} docs" + echo "Documentation for tag ${TAG_NAME} committed to gh-pages branch!" + echo "Push to remote to deploy to GitHub Pages" +fi diff --git a/typedoc.json b/typedoc.json new file mode 100644 index 000000000..70a5ec277 --- /dev/null +++ b/typedoc.json @@ -0,0 +1,6 @@ +{ + "$schema": "https://typedoc.org/schema.json", + "entryPoints": ["src"], + "entryPointStrategy": "expand", + "exclude": ["**/*.test.ts", "**/__mocks__/**", "**/examples/**", "**/integration-tests/**", "**/spec.types.ts", "**/zodTestMatrix.ts"] +}