Skip to content

Commit 02f0d72

Browse files
patnikopatniko
authored
Add documentation code validation system (#356)
* Update client initialization and session creation syntax in documentation * Update client initialization syntax in documentation and enhance event subscription methods * Refactor error handling messages and improve documentation links * Update context usage in session management examples across documentation * Add documentation code validation system - Add scripts/docs-validation/ tooling to extract and validate code blocks - Extract code from markdown and validate with language-specific compilers - TypeScript: tsc --noEmit type checking - Python: py_compile + mypy for syntax and type checking - Go: go build for compilation checking - C#: dotnet build for compilation checking - Add GitHub Actions workflow (.github/workflows/docs-validation.yml) - Runs on PRs touching docs/ or SDK source files - Parallel validation jobs for each language - Add justfile tasks: validate-docs, validate-docs-ts, etc. - Fix Go docs: client.Start() -> client.Start(ctx) - All 157 code blocks now pass validation * Simplify docs validation workflow - Remove separate extract job and artifact upload/download - Each language job now extracts and validates independently - Jobs run in parallel without dependencies - Remove docs/.gitignore (no longer needed) * Remove accidentally committed .validation directory * Add docs/.validation to gitignore * Update CreateSession call to include context parameter * Fix CI failures: add skip markers for type signatures and partial snippets - Add skip markers to Python type signature definitions (hooks) - Add skip markers to C# partial config snippets (mcp/debugging.md) - Add skip markers to Python snippets using undefined variables * Add GitHub Actions job summary for docs validation Shows a summary table in the PR with: - Pass/fail status per language - Total code blocks validated - Details of any failures * Fix C# docs validation by wrapping code in classes The C# documentation validation was failing because: 1. Multiple files had top-level statements (C# only allows one per project) 2. Some snippets were missing the 'using GitHub.Copilot.SDK;' directive This fix: - Wraps C# code snippets without class/namespace in unique static classes - Preserves existing using directives and adds SDK using if missing - Detects async code (await keyword) and creates async Main methods - Skips wrapping for code that already has structure (classes, namespaces, delegates) * Add skip markers for docs validation in hook documentation * Add skip markers for partial C# code snippets These code snippets are intentionally partial - they show specific configurations assuming a 'client' or 'session' variable already exists. The validation cannot compile them standalone, so they're skipped. Also fixed mcp/overview.md to use List<string> instead of string[] to match the actual SDK types.
1 parent fc731f0 commit 02f0d72

22 files changed

+2699
-77
lines changed

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

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
name: "Documentation Validation"
2+
3+
on:
4+
pull_request:
5+
paths:
6+
- 'docs/**'
7+
- 'nodejs/src/**'
8+
- 'python/copilot/**'
9+
- 'go/**/*.go'
10+
- 'dotnet/src/**'
11+
- 'scripts/docs-validation/**'
12+
- '.github/workflows/docs-validation.yml'
13+
workflow_dispatch:
14+
merge_group:
15+
16+
permissions:
17+
contents: read
18+
19+
jobs:
20+
validate-typescript:
21+
name: "Validate TypeScript"
22+
runs-on: ubuntu-latest
23+
steps:
24+
- uses: actions/checkout@v4
25+
26+
- uses: actions/setup-node@v4
27+
with:
28+
node-version: 22
29+
cache: "npm"
30+
cache-dependency-path: "nodejs/package-lock.json"
31+
32+
- name: Install SDK dependencies
33+
working-directory: nodejs
34+
run: npm ci --ignore-scripts
35+
36+
- name: Install validation dependencies
37+
working-directory: scripts/docs-validation
38+
run: npm ci
39+
40+
- name: Extract and validate TypeScript
41+
working-directory: scripts/docs-validation
42+
run: npm run extract && npm run validate:ts
43+
44+
validate-python:
45+
name: "Validate Python"
46+
runs-on: ubuntu-latest
47+
steps:
48+
- uses: actions/checkout@v4
49+
50+
- uses: actions/setup-node@v4
51+
with:
52+
node-version: 22
53+
54+
- uses: actions/setup-python@v5
55+
with:
56+
python-version: "3.12"
57+
58+
- name: Install uv
59+
uses: astral-sh/setup-uv@v5
60+
61+
- name: Install SDK dependencies
62+
working-directory: python
63+
run: uv sync
64+
65+
- name: Install mypy
66+
run: pip install mypy
67+
68+
- name: Install validation dependencies
69+
working-directory: scripts/docs-validation
70+
run: npm ci
71+
72+
- name: Extract and validate Python
73+
working-directory: scripts/docs-validation
74+
run: npm run extract && npm run validate:py
75+
76+
validate-go:
77+
name: "Validate Go"
78+
runs-on: ubuntu-latest
79+
steps:
80+
- uses: actions/checkout@v4
81+
82+
- uses: actions/setup-node@v4
83+
with:
84+
node-version: 22
85+
86+
- uses: actions/setup-go@v5
87+
with:
88+
go-version: "1.23"
89+
cache-dependency-path: "go/go.sum"
90+
91+
- name: Install validation dependencies
92+
working-directory: scripts/docs-validation
93+
run: npm ci
94+
95+
- name: Extract and validate Go
96+
working-directory: scripts/docs-validation
97+
run: npm run extract && npm run validate:go
98+
99+
validate-csharp:
100+
name: "Validate C#"
101+
runs-on: ubuntu-latest
102+
steps:
103+
- uses: actions/checkout@v4
104+
105+
- uses: actions/setup-node@v4
106+
with:
107+
node-version: 22
108+
109+
- uses: actions/setup-dotnet@v4
110+
with:
111+
dotnet-version: "8.0.x"
112+
113+
- name: Install validation dependencies
114+
working-directory: scripts/docs-validation
115+
run: npm ci
116+
117+
- name: Restore SDK dependencies
118+
working-directory: dotnet
119+
run: dotnet restore
120+
121+
- name: Extract and validate C#
122+
working-directory: scripts/docs-validation
123+
run: npm run extract && npm run validate:cs

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
2+
# Documentation validation output
3+
docs/.validation/

‎docs/auth/byok.md‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -104,13 +104,14 @@ import (
104104
)
105105

106106
func main() {
107+
ctx := context.Background()
107108
client := copilot.NewClient(nil)
108-
if err := client.Start(); err != nil {
109+
if err := client.Start(ctx); err != nil {
109110
panic(err)
110111
}
111112
defer client.Stop()
112113

113-
session, err := client.CreateSession(context.Background(), &copilot.SessionConfig{
114+
session, err := client.CreateSession(ctx, &copilot.SessionConfig{
114115
Model: "gpt-5.2-codex", // Your deployment name
115116
Provider: &copilot.ProviderConfig{
116117
Type: "openai",
@@ -123,9 +124,9 @@ func main() {
123124
panic(err)
124125
}
125126

126-
response, err := session.SendAndWait(copilot.MessageOptions{
127+
response, err := session.SendAndWait(ctx, copilot.MessageOptions{
127128
Prompt: "What is 2+2?",
128-
}, 0)
129+
})
129130
if err != nil {
130131
panic(err)
131132
}
@@ -325,6 +326,7 @@ const session = await client.createSession({
325326

326327
For Azure OpenAI endpoints (`*.openai.azure.com`), use the correct type:
327328

329+
<!-- docs-validate: skip -->
328330
```typescript
329331
// ❌ Wrong: Using "openai" type with native Azure endpoint
330332
provider: {
@@ -341,6 +343,7 @@ provider: {
341343

342344
However, if your Azure AI Foundry deployment provides an OpenAI-compatible endpoint path (e.g., `/openai/v1/`), use `type: "openai"`:
343345

346+
<!-- docs-validate: skip -->
344347
```typescript
345348
// ✅ Correct: OpenAI-compatible Azure AI Foundry endpoint
346349
provider: {

‎docs/auth/index.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,7 @@ await client.start()
5050
<details>
5151
<summary><strong>Go</strong></summary>
5252

53+
<!-- docs-validate: skip -->
5354
```go
5455
import copilot "github.com/github/copilot-sdk/go"
5556

@@ -119,6 +120,7 @@ await client.start()
119120
<details>
120121
<summary><strong>Go</strong></summary>
121122

123+
<!-- docs-validate: skip -->
122124
```go
123125
import copilot "github.com/github/copilot-sdk/go"
124126

@@ -133,6 +135,7 @@ client := copilot.NewClient(&copilot.ClientOptions{
133135
<details>
134136
<summary><strong>.NET</strong></summary>
135137

138+
<!-- docs-validate: skip -->
136139
```csharp
137140
using GitHub.Copilot.SDK;
138141

@@ -251,6 +254,7 @@ const client = new CopilotClient({
251254
<details>
252255
<summary><strong>Python</strong></summary>
253256

257+
<!-- docs-validate: skip -->
254258
```python
255259
client = CopilotClient({
256260
"use_logged_in_user": False, # Only use explicit tokens
@@ -262,6 +266,7 @@ client = CopilotClient({
262266
<details>
263267
<summary><strong>Go</strong></summary>
264268

269+
<!-- docs-validate: skip -->
265270
```go
266271
client := copilot.NewClient(&copilot.ClientOptions{
267272
UseLoggedInUser: copilot.Bool(false), // Only use explicit tokens

‎docs/debugging.md‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -36,14 +36,15 @@ const client = new CopilotClient({
3636
```python
3737
from copilot import CopilotClient
3838

39-
client = CopilotClient(log_level="debug")
39+
client = CopilotClient({"log_level": "debug"})
4040
```
4141

4242
</details>
4343

4444
<details>
4545
<summary><strong>Go</strong></summary>
4646

47+
<!-- docs-validate: skip -->
4748
```go
4849
import copilot "github.com/github/copilot-sdk/go"
4950

@@ -57,6 +58,7 @@ client := copilot.NewClient(&copilot.ClientOptions{
5758
<details>
5859
<summary><strong>.NET</strong></summary>
5960

61+
<!-- docs-validate: skip -->
6062
```csharp
6163
using GitHub.Copilot.SDK;
6264
using Microsoft.Extensions.Logging;
@@ -108,6 +110,7 @@ const client = new CopilotClient({
108110
<details>
109111
<summary><strong>Go</strong></summary>
110112

113+
<!-- docs-validate: skip -->
111114
```go
112115
// The Go SDK does not currently support passing extra CLI arguments.
113116
// For custom log directories, run the CLI manually with --log-dir
@@ -161,7 +164,7 @@ var client = new CopilotClient(new CopilotClientOptions
161164
<summary><strong>Python</strong></summary>
162165

163166
```python
164-
client = CopilotClient(cli_path="/usr/local/bin/copilot")
167+
client = CopilotClient({"cli_path": "/usr/local/bin/copilot"})
165168
```
166169
</details>
167170

@@ -214,7 +217,7 @@ var client = new CopilotClient(new CopilotClientOptions
214217

215218
```python
216219
import os
217-
client = CopilotClient(github_token=os.environ.get("GITHUB_TOKEN"))
220+
client = CopilotClient({"github_token": os.environ.get("GITHUB_TOKEN")})
218221
```
219222
</details>
220223

0 commit comments

Comments
 (0)