|
| 1 | +#!/usr/bin/env bash |
| 2 | +# |
| 3 | +# Generate combined V1 + V2 TypeDoc documentation. |
| 4 | +# |
| 5 | +# V1 docs (from the v1.x branch) are placed at the root. |
| 6 | +# V2 docs (from main) are placed under /v2/. |
| 7 | +# |
| 8 | +# This script can be run from any branch — it fetches both v1.x and main |
| 9 | +# via git worktrees. |
| 10 | +# |
| 11 | +# Usage: |
| 12 | +# scripts/generate-multidoc.sh [output-dir] |
| 13 | +# |
| 14 | +# Default output directory: tmp/docs-combined |
| 15 | +# |
| 16 | +set -euo pipefail |
| 17 | + |
| 18 | +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" |
| 19 | +REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)" |
| 20 | +OUTPUT_DIR="${1:-$REPO_ROOT/tmp/docs-combined}" |
| 21 | +V1_WORKTREE="$REPO_ROOT/.worktrees/v1-docs" |
| 22 | +V2_WORKTREE="$REPO_ROOT/.worktrees/v2-docs" |
| 23 | + |
| 24 | +cleanup() { |
| 25 | + echo "Cleaning up worktrees..." |
| 26 | + cd "$REPO_ROOT" |
| 27 | + git worktree remove --force "$V1_WORKTREE" 2>/dev/null || true |
| 28 | + git worktree remove --force "$V2_WORKTREE" 2>/dev/null || true |
| 29 | +} |
| 30 | +trap cleanup EXIT |
| 31 | + |
| 32 | +rm -rf "$OUTPUT_DIR" |
| 33 | +mkdir -p "$OUTPUT_DIR" |
| 34 | + |
| 35 | +# --------------------------------------------------------------------------- |
| 36 | +# Step 1: Generate V1 docs from v1.x branch |
| 37 | +# --------------------------------------------------------------------------- |
| 38 | +echo "=== Generating V1 docs ===" |
| 39 | + |
| 40 | +git fetch origin v1.x |
| 41 | + |
| 42 | +git worktree remove --force "$V1_WORKTREE" 2>/dev/null || true |
| 43 | +rm -rf "$V1_WORKTREE" |
| 44 | +git worktree add "$V1_WORKTREE" "origin/v1.x" --detach |
| 45 | + |
| 46 | +cd "$V1_WORKTREE" |
| 47 | +npm install |
| 48 | +npm install --save-dev typedoc@^0.28.14 |
| 49 | + |
| 50 | +cat > typedoc.json << 'TYPEDOC_EOF' |
| 51 | +{ |
| 52 | + "name": "MCP TypeScript SDK", |
| 53 | + "entryPoints": [ |
| 54 | + "src/client/index.ts", |
| 55 | + "src/server/index.ts", |
| 56 | + "src/shared/protocol.ts", |
| 57 | + "src/shared/transport.ts", |
| 58 | + "src/types.ts", |
| 59 | + "src/inMemory.ts", |
| 60 | + "src/validation/index.ts", |
| 61 | + "src/experimental/index.ts" |
| 62 | + ], |
| 63 | + "tsconfig": "tsconfig.json", |
| 64 | + "out": "tmp/docs", |
| 65 | + "exclude": [ |
| 66 | + "**/*.test.ts", |
| 67 | + "**/__fixtures__/**", |
| 68 | + "**/__mocks__/**", |
| 69 | + "src/examples/**" |
| 70 | + ], |
| 71 | + "projectDocuments": [ |
| 72 | + "docs/server.md", |
| 73 | + "docs/client.md", |
| 74 | + "docs/capabilities.md", |
| 75 | + "docs/protocol.md", |
| 76 | + "docs/faq.md" |
| 77 | + ], |
| 78 | + "navigationLinks": { |
| 79 | + "V2 Docs": "/v2/" |
| 80 | + }, |
| 81 | + "headings": { |
| 82 | + "readme": false |
| 83 | + }, |
| 84 | + "skipErrorChecking": true |
| 85 | +} |
| 86 | +TYPEDOC_EOF |
| 87 | + |
| 88 | +# Rewrite relative .ts links to point to GitHub source instead of media downloads |
| 89 | +V1_GITHUB="https://github.com/modelcontextprotocol/typescript-sdk/blob/v1.x" |
| 90 | +sed -i "s|(src/examples/|(${V1_GITHUB}/src/examples/|g" README.md |
| 91 | +sed -i "s|(../src/examples/|(${V1_GITHUB}/src/examples/|g" docs/*.md |
| 92 | + |
| 93 | +npx typedoc |
| 94 | + |
| 95 | +cp -r "$V1_WORKTREE/tmp/docs/"* "$OUTPUT_DIR/" |
| 96 | + |
| 97 | +# --------------------------------------------------------------------------- |
| 98 | +# Step 2: Generate V2 docs from main branch |
| 99 | +# --------------------------------------------------------------------------- |
| 100 | +echo "=== Generating V2 docs ===" |
| 101 | + |
| 102 | +git fetch origin main |
| 103 | + |
| 104 | +git worktree remove --force "$V2_WORKTREE" 2>/dev/null || true |
| 105 | +rm -rf "$V2_WORKTREE" |
| 106 | +git worktree add "$V2_WORKTREE" "origin/main" --detach |
| 107 | + |
| 108 | +cd "$V2_WORKTREE" |
| 109 | +pnpm install |
| 110 | +pnpm -r --filter='./packages/**' build |
| 111 | + |
| 112 | +# Write the V2 pre-release banner script |
| 113 | +cat > docs/v2-banner.js << 'BANNER_EOF' |
| 114 | +document.addEventListener("DOMContentLoaded", function () { |
| 115 | + var banner = document.createElement("div"); |
| 116 | + banner.innerHTML = |
| 117 | + "This documents a <strong>pre-release</strong> version of the SDK. Expect breaking changes. For the stable SDK, see the <a href='/'>V1 docs</a>."; |
| 118 | + banner.style.cssText = |
| 119 | + "background:#fff3cd;color:#856404;border-bottom:1px solid #ffc107;padding:8px 16px;text-align:center;font-size:14px;"; |
| 120 | + banner.querySelector("a").style.cssText = "color:#856404;text-decoration:underline;"; |
| 121 | + document.body.insertBefore(banner, document.body.firstChild); |
| 122 | +
|
| 123 | +
|
| 124 | +}); |
| 125 | +BANNER_EOF |
| 126 | + |
| 127 | +# Patch the V2 typedoc config to add navigation links, base URL, and banner |
| 128 | +node -e " |
| 129 | +import fs from 'fs'; |
| 130 | +const cfg = fs.readFileSync('typedoc.config.mjs', 'utf8'); |
| 131 | +const patched = cfg.replace( |
| 132 | + /export default \{/, |
| 133 | + \"export default {\\n hostedBaseUrl: 'https://modelcontextprotocol.github.io/typescript-sdk/v2/',\\n customJs: 'docs/v2-banner.js',\" |
| 134 | +).replace( |
| 135 | + /navigation:/, |
| 136 | + \"navigationLinks: {\\n 'V1 Docs': '/',\\n },\\n navigation:\" |
| 137 | +); |
| 138 | +fs.writeFileSync('typedoc.config.mjs', patched); |
| 139 | +" |
| 140 | + |
| 141 | +npx typedoc # outputs to tmp/docs/ per typedoc.config.mjs |
| 142 | + |
| 143 | +mkdir -p "$OUTPUT_DIR/v2" |
| 144 | +cp -r "$V2_WORKTREE/tmp/docs/"* "$OUTPUT_DIR/v2/" |
| 145 | + |
| 146 | +cd "$REPO_ROOT" |
| 147 | +echo "=== Combined docs generated at $OUTPUT_DIR ===" |
0 commit comments