Skip to content

Commit 357a7ce

Browse files
maxisbeymaxisbey
committed
ci: deploy docs to py.sdk.modelcontextprotocol.io via GitHub Pages artifact
Build both v1.x and main into a single Pages artifact (v1 at /, v2 at /v2/), deployed via actions/deploy-pages on push to either branch. This fixes the 404 at the custom domain (which DNS already points at GitHub Pages but the repo never claimed) and stops the two branches from overwriting each other's docs on release. The legacy mkdocs gh-deploy path (docs-publish job in publish-pypi.yml and the manual workflow) is removed; the gh-pages branch can be deleted once the new deploy is confirmed working. Closes #2614. Supersedes #2615.
1 parent 161834d commit 357a7ce

8 files changed

Lines changed: 117 additions & 65 deletions

File tree

‎.github/workflows/deploy-docs.yml‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
name: Deploy Docs
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
- v1.x
8+
paths:
9+
- docs/**
10+
- mkdocs.yml
11+
- src/mcp/**
12+
- scripts/build-docs.sh
13+
- pyproject.toml
14+
- uv.lock
15+
- .github/workflows/deploy-docs.yml
16+
workflow_dispatch:
17+
18+
concurrency:
19+
group: deploy-docs
20+
cancel-in-progress: false
21+
22+
jobs:
23+
deploy-docs:
24+
runs-on: ubuntu-latest
25+
26+
permissions:
27+
contents: read
28+
pages: write
29+
id-token: write
30+
31+
environment:
32+
name: github-pages
33+
url: ${{ steps.deployment.outputs.page_url }}
34+
35+
steps:
36+
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
37+
38+
- name: Install uv
39+
uses: astral-sh/setup-uv@803947b9bd8e9f986429fa0c5a41c367cd732b41 # v7.2.1
40+
with:
41+
enable-cache: true
42+
version: 0.9.5
43+
44+
- name: Build combined docs (v1.x at /, main at /v2/)
45+
run: bash scripts/build-docs.sh site
46+
47+
- name: Configure Pages
48+
uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
49+
50+
- name: Upload Pages artifact
51+
uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
52+
with:
53+
path: site
54+
55+
- name: Deploy to GitHub Pages
56+
id: deployment
57+
uses: actions/deploy-pages@cd2ce8fcbc39b97be8ca5fce6e763baed58fa128 # v5.0.0

‎.github/workflows/publish-docs-manually.yml‎

Lines changed: 0 additions & 35 deletions
This file was deleted.

‎.github/workflows/publish-pypi.yml‎

Lines changed: 0 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -51,32 +51,3 @@ jobs:
5151

5252
- name: Publish package distributions to PyPI
5353
uses: pypa/gh-action-pypi-publish@ed0c53931b1dc9bd32cbe73a98c7f6766f8a527e # release/v1
54-
55-
docs-publish:
56-
runs-on: ubuntu-latest
57-
needs: ["pypi-publish"]
58-
permissions:
59-
contents: write
60-
steps:
61-
- uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4.3.1
62-
- name: Configure Git Credentials
63-
run: |
64-
git config user.name github-actions[bot]
65-
git config user.email 41898282+github-actions[bot]@users.noreply.github.com
66-
67-
- name: Install uv
68-
uses: astral-sh/setup-uv@803947b9bd8e9f986429fa0c5a41c367cd732b41 # v7.2.1
69-
with:
70-
enable-cache: true
71-
version: 0.9.5
72-
73-
- run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
74-
- uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306 # v5.0.3
75-
with:
76-
key: mkdocs-material-${{ env.cache_id }}
77-
path: .cache
78-
restore-keys: |
79-
mkdocs-material-
80-
81-
- run: uv sync --frozen --group docs
82-
- run: uv run --frozen --no-sync mkdocs gh-deploy --force

‎.gitignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -143,6 +143,7 @@ venv.bak/
143143

144144
# mkdocs documentation
145145
/site
146+
/.worktrees/
146147

147148
# mypy
148149
.mypy_cache/

‎docs/index.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
# MCP Python SDK
22

3+
!!! info "You are viewing the in-development v2 documentation"
4+
For the current stable release, see the [v1.x documentation](https://py.sdk.modelcontextprotocol.io/).
5+
36
The **Model Context Protocol (MCP)** allows applications to provide context for LLMs in a standardized way, separating the concerns of providing context from the actual LLM interaction.
47

58
This Python SDK implements the full MCP specification, making it easy to:

‎mkdocs.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ strict: true
55
repo_name: modelcontextprotocol/python-sdk
66
repo_url: https://github.com/modelcontextprotocol/python-sdk
77
edit_uri: edit/main/docs/
8-
site_url: https://modelcontextprotocol.github.io/python-sdk
8+
site_url: https://py.sdk.modelcontextprotocol.io/v2/
99

1010
# TODO(Marcelo): Add Anthropic copyright?
1111
# copyright: © Model Context Protocol 2025 to present

‎pyproject.toml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -115,6 +115,7 @@ bump = true
115115

116116
[project.urls]
117117
Homepage = "https://modelcontextprotocol.io"
118+
Documentation = "https://py.sdk.modelcontextprotocol.io/v2/"
118119
Repository = "https://github.com/modelcontextprotocol/python-sdk"
119120
Issues = "https://github.com/modelcontextprotocol/python-sdk/issues"
120121

‎scripts/build-docs.sh‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
#!/usr/bin/env bash
2+
#
3+
# Build combined v1 + v2 MkDocs documentation for GitHub Pages.
4+
#
5+
# v1 docs (from the v1.x branch) are placed at the site root.
6+
# v2 docs (from main) are placed under /v2/.
7+
#
8+
# Both branches are fetched fresh from origin, so the output is identical
9+
# regardless of which branch triggered the workflow. This script is intended
10+
# to run in CI; for local single-branch preview use `uv run mkdocs serve`.
11+
#
12+
# Usage:
13+
# scripts/build-docs.sh [output-dir]
14+
#
15+
# Default output directory: site
16+
#
17+
set -euo pipefail
18+
19+
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
20+
REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
21+
OUTPUT_DIR="$(cd "$REPO_ROOT" && mkdir -p "${1:-site}" && cd "${1:-site}" && pwd)"
22+
V1_WORKTREE="$REPO_ROOT/.worktrees/v1-docs"
23+
V2_WORKTREE="$REPO_ROOT/.worktrees/v2-docs"
24+
25+
cleanup() {
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+
rmdir "$REPO_ROOT/.worktrees" 2>/dev/null || true
30+
}
31+
trap cleanup EXIT
32+
33+
rm -rf "${OUTPUT_DIR:?}"/*
34+
35+
build_branch() {
36+
local branch="$1" worktree="$2" dest="$3"
37+
38+
echo "=== Building docs for ${branch} ==="
39+
git fetch origin "$branch"
40+
git worktree remove --force "$worktree" 2>/dev/null || true
41+
rm -rf "$worktree"
42+
git worktree add --detach "$worktree" "origin/${branch}"
43+
44+
(
45+
cd "$worktree"
46+
uv sync --frozen --group docs
47+
uv run --frozen --no-sync mkdocs build --site-dir "$dest"
48+
)
49+
}
50+
51+
build_branch v1.x "$V1_WORKTREE" "$OUTPUT_DIR"
52+
build_branch main "$V2_WORKTREE" "$OUTPUT_DIR/v2"
53+
54+
echo "=== Combined docs built at $OUTPUT_DIR ==="

0 commit comments

Comments
 (0)