Add deploy-docs-preview (#1498)

Author: samuelcolvin

.github/set_docs_main_preview_url.py

@@ -0,0 +1,56 @@
+import json
+import os
+import re
+import typing
+
+import httpx
+
+DEPLOY_OUTPUT = os.environ['DEPLOY_OUTPUT']
+GITHUB_TOKEN = os.environ['GITHUB_TOKEN']
+REPOSITORY = os.environ['REPOSITORY']
+REF = os.environ['REF']
+ENVIRONMENT = 'deploy-docs-preview'
+
+m = re.search(r'https://(\S+)\.workers\.dev', DEPLOY_OUTPUT)
+assert m, f'Could not find worker URL in {DEPLOY_OUTPUT!r}'
+
+worker_name = m.group(1)
+m = re.search(r'Current Version ID: ([^-]+)', DEPLOY_OUTPUT)
+assert m, f'Could not find version ID in {DEPLOY_OUTPUT!r}'
+
+version_id = m.group(1)
+preview_url = f'https://{version_id}-{worker_name}.workers.dev'
+
+gh_headers = {
+    'Accept': 'application/vnd.github+json',
+    'Authorization': f'Bearer {GITHUB_TOKEN}',
+    'X-GitHub-Api-Version': '2022-11-28',
+}
+
+deployment_url = f'https://api.github.com/repos/{REPOSITORY}/deployments'
+deployment_data: dict[str, typing.Any] = {
+    'ref': REF,
+    'task': 'docs preview',
+    'environment': ENVIRONMENT,
+    'auto_merge': False,
+    'required_contexts': [],
+    'payload': json.dumps({
+        'preview_url': preview_url,
+        'worker_name': worker_name,
+        'version_id': version_id,
+    })
+}
+r = httpx.post(deployment_url, headers=gh_headers, json=deployment_data)
+print(f'POST {deployment_url}: {r.status_code}')  # {r.text}
+r.raise_for_status()
+deployment_id = r.json()['id']
+
+status_url = f'https://api.github.com/repos/{REPOSITORY}/deployments/{deployment_id}/statuses'
+status_data = {
+    'environment': ENVIRONMENT,
+    'environment_url': preview_url,
+    'state': 'success',
+}
+r = httpx.post(status_url, headers=gh_headers, json=status_data)
+print(f'POST {status_url}: {r.status_code}')  # {r.text}
+r.raise_for_status()

.github/set_docs_preview_url.py renamed to .github/set_docs_pr_preview_url.py

@@ -92,7 +92,7 @@ jobs:
           GITHUB_EVENT_JSON: ${{ toJSON(github.event) }}
 
       - name: Set preview URL
-        run: uv run --with httpx .github/set_docs_preview_url.py
+        run: uv run --with httpx .github/set_docs_pr_preview_url.py
         env:
           DEPLOY_OUTPUT: ${{ steps.deploy.outputs.command-output }}
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/after-ci.yml

@@ -311,6 +311,48 @@ jobs:
         env:
           ALGOLIA_WRITE_API_KEY: ${{ secrets.ALGOLIA_WRITE_API_KEY }}
 
+  deploy-docs-preview:
+    needs: [check]
+    if: success() && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    environment:
+      name: deploy-docs-preview
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+      - run: npm install
+        working-directory: docs-site
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - uses: actions/download-artifact@v4
+        with:
+          name: site
+          path: site
+
+      - uses: cloudflare/wrangler-action@v3
+        id: deploy
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          environment: previews
+          workingDirectory: docs-site
+          command: >
+            deploy
+            --var GIT_COMMIT_SHA:${{ github.sha }}
+            --var GIT_BRANCH:main
+
+      - name: Set preview URL
+        run: uv run --with httpx .github/set_docs_main_preview_url.py
+        env:
+          DEPLOY_OUTPUT: ${{ steps.deploy.outputs.command-output }}
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPOSITORY: ${{ github.repository }}
+          REF: ${{ github.event.workflow_run.head_sha }}
+
   # TODO(Marcelo): We need to split this into two jobs: `build` and `release`.
   release:
     needs: [check]

.github/workflows/ci.yml

@@ -66,20 +66,24 @@ async function getChangelog(kv: KVNamespace, commitSha: string): Promise<string>
 
 interface Release {
   name: string
+  tag_name: string
   body: string
   html_url: string
 }
 
+const githubIcon = `<span class="twemoji"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12"></path></svg></span>`
+
 function prepRelease(release: Release): string {
   const body = release.body
     .replace(/(#+)/g, (m) => `##${m}`)
     .replace(/https:\/\/github.com\/pydantic\/pydantic-ai\/pull\/(\d+)/g, (url, id) => `[#${id}](${url})`)
-    .replace(/\*\*Full Changelog\*\*: (\S+)/, (_, url) => `[Compare diff](${url})`)
+    .replace(/(\s)@([\w\-]+)/g, (_, s, u) => `${s}[@${u}](https://github.com/${u})`)
+    .replace(/\*\*Full Changelog\*\*: (\S+)/, (_, url) => `[${githubIcon} Compare diff](${url}).`)
   return `
 ### ${release.name}
 
 ${body}
 
-[View on GitHub](${release.html_url})
+[${githubIcon} View ${release.tag_name} release](${release.html_url}).
 `
 }

docs-site/src/index.ts

@@ -3,9 +3,9 @@
 PydanticAI is still pre-version 1, so breaking changes will occur, however:
 
 - We try to minimize them as much as possible.
-- We will use minor version bumps to signify breaking changes.
-- Wherever possible we'll deprecate old features so code continues to work with deprecation warnings when changing the public API.
-- We intend to release V1 in summer 2025, and then follow strict semantic versioning, e.g. no intentional breaking changes except in major versions.
+- We use minor version bumps to signify breaking changes.
+- Wherever possible we deprecate old features so code continues to work with deprecation warnings when changing the public API.
+- We intend to release V1 in summer 2025, and then follow strict semantic versioning, e.g. no intentional breaking changes except in minor or patch versions.
 
 ## Breaking Changes
 
@@ -27,11 +27,11 @@ See [#1484](https://github.com/pydantic/pydantic-ai/pull/1484) — `format_as_xm
 </div>
 
 <script>
-  async function getChangelog() {
-    const r = await fetch('/changelog.html');
+  fetch('/changelog.html').then(r => {
     if (r.ok) {
-      document.getElementById('display-changelog').innerHTML = await r.text();
+      r.text().then(t => {
+        document.getElementById('display-changelog').innerHTML = t;
+      });
     }
-  }
-  getChangelog();
+  });
 </script>