Add API documentation with GitHub Pages deployment (#1109)
Co-authored-by: Konstantin Konstantinov <konstantin@mach5technology.com>
This commit is contained in:
Jonathan Hefner
GitHub
parent
9fc7e28f48
commit
25f288be1b
1 changed files with 11403 additions and 2391 deletions
186
scripts/generate-gh-pages.sh
Executable file
186
scripts/generate-gh-pages.sh
Executable file
|
|
@ -0,0 +1,186 @@
|
|||
#!/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/)
|
||||
# - Generates _data/latest_version.yml for Jekyll template
|
||||
# - Generates versions.json manifest showing all package versions
|
||||
# - Copies static Jekyll template files from .github/pages/
|
||||
# - 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`
|
||||
# Or with a package-scoped tag: `generate-gh-pages.sh @modelcontextprotocol/client@1.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
|
||||
# Supports both simple tags (v1.2.3) and package-scoped tags (@scope/package@1.2.3)
|
||||
if [[ "${TAG_NAME}" =~ @[^@]+@([0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.-]+)?)$ ]]; then
|
||||
# Package-scoped tag (e.g., @modelcontextprotocol/client@1.2.3)
|
||||
VERSION="v${BASH_REMATCH[1]}"
|
||||
elif [[ "${TAG_NAME}" =~ ([0-9]+\.[0-9]+\.[0-9]+(-[a-zA-Z0-9.-]+)?)$ ]]; then
|
||||
# Simple version tag (e.g., v1.2.3 or 1.2.3)
|
||||
VERSION="v${BASH_REMATCH[1]}"
|
||||
else
|
||||
echo "Error: Must specify a tag name that contains a valid semantic version"
|
||||
echo "Usage: ${0} <tag-name>"
|
||||
echo "Examples:"
|
||||
echo " ${0} 1.2.3"
|
||||
echo " ${0} v2.0.0-rc.1"
|
||||
echo " ${0} @modelcontextprotocol/client@1.2.3"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "Generating documentation for tag: ${TAG_NAME}"
|
||||
echo "Documentation version directory: ${VERSION}"
|
||||
|
||||
# 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}" && pnpm install --frozen-lockfile --ignore-scripts)
|
||||
|
||||
echo "Generating TypeDoc documentation..."
|
||||
(cd "${source_dir}" && pnpm run docs --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
|
||||
}
|
||||
|
||||
# Gets list of public (non-private) package paths from pnpm workspace
|
||||
get_public_packages() {
|
||||
local source_dir="${1}"
|
||||
(cd "${source_dir}" && pnpm list -r --json --depth -1 | node -e '
|
||||
const data = JSON.parse(require("fs").readFileSync(0, "utf8"));
|
||||
data.filter(p => !p.private).forEach(p => console.log(p.path));
|
||||
')
|
||||
}
|
||||
|
||||
# Generates versions.json manifest showing all package versions
|
||||
# This helps users understand which versions of each package are included
|
||||
generate_versions_manifest() {
|
||||
local source_dir="${1}"
|
||||
local output_dir="${2}"
|
||||
local tag_name="${3}"
|
||||
|
||||
echo "Generating versions.json manifest..."
|
||||
|
||||
# Get list of public packages dynamically from pnpm workspace
|
||||
local packages
|
||||
packages=$(get_public_packages "${source_dir}")
|
||||
|
||||
# Start JSON object
|
||||
local json="{\n"
|
||||
json+=" \"generated_from_tag\": \"${tag_name}\",\n"
|
||||
json+=" \"generated_at\": \"$(date -u +%Y-%m-%dT%H:%M:%SZ)\",\n"
|
||||
json+=" \"packages\": {\n"
|
||||
|
||||
local first=true
|
||||
while IFS= read -r pkg_path; do
|
||||
local pkg_json="${pkg_path}/package.json"
|
||||
if [ -f "${pkg_json}" ]; then
|
||||
local pkg_name=$(node -p "require('${pkg_json}').name")
|
||||
local pkg_version=$(node -p "require('${pkg_json}').version")
|
||||
|
||||
if [ "${first}" = true ]; then
|
||||
first=false
|
||||
else
|
||||
json+=",\n"
|
||||
fi
|
||||
json+=" \"${pkg_name}\": \"${pkg_version}\""
|
||||
fi
|
||||
done <<< "${packages}"
|
||||
|
||||
json+="\n }\n}"
|
||||
|
||||
# Write the manifest
|
||||
echo -e "${json}" > "${output_dir}/versions.json"
|
||||
echo "Created ${output_dir}/versions.json"
|
||||
}
|
||||
|
||||
# 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 versions manifest showing all package versions
|
||||
generate_versions_manifest "${TAG_WORKTREE_DIR}" "${VERSION}" "${TAG_NAME}"
|
||||
|
||||
# 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 {} . \;
|
||||
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
|
||||
Loading…
Reference in a new issue