Skip to content

Commit 102c842

Browse files
torresmateotorresmateo
authored
Merge branch 'main' into mateo/dev-284-add-co-pilot-to-docs
2 parents 85d334c + cb4206b commit 102c842

File tree

83 files changed

+5282
-1399
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

83 files changed

+5282
-1399
lines changed

‎.env.local.example‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
# Copy this file to .env.local and fill in the values
2+
# cp .env.example .env.local
3+
4+
# Required for generating llms.txt with AI-powered summaries
5+
OPENAI_API_KEY=
6+
7+
# Optional: Enables AI-powered style tools locally
8+
# Used by: vale:fix, vale:review, vale:editorial
9+
# Get a key from https://console.anthropic.com/
10+
# Falls back to OPENAI_API_KEY if not set
11+
ANTHROPIC_API_KEY=

‎.github/workflows/style-review.yml‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
name: Style Review
2+
3+
on:
4+
workflow_dispatch:
5+
inputs:
6+
pr_number:
7+
description: "PR number to review"
8+
required: true
9+
type: number
10+
pull_request:
11+
types: [opened, synchronize, reopened]
12+
paths:
13+
- "app/en/**/*.md"
14+
- "app/en/**/*.mdx"
15+
16+
permissions:
17+
contents: read
18+
pull-requests: write
19+
20+
jobs:
21+
style-review:
22+
name: Vale Style Review
23+
runs-on: ubuntu-latest
24+
# Skip editorial PRs to prevent automation loops
25+
if: "!startsWith(github.head_ref, 'style/editorial-')"
26+
27+
steps:
28+
- name: Checkout repository
29+
uses: actions/checkout@v4
30+
with:
31+
# For pull_request events, checkout the PR head commit directly
32+
ref: ${{ github.event.pull_request.head.sha || '' }}
33+
34+
- name: Checkout PR branch
35+
if: github.event_name == 'workflow_dispatch'
36+
run: gh pr checkout ${{ inputs.pr_number }}
37+
env:
38+
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
39+
40+
- name: Use Node.js
41+
uses: actions/setup-node@v4
42+
with:
43+
node-version: "22.x"
44+
45+
- name: Install pnpm
46+
run: npm install -g pnpm
47+
48+
- name: Install dependencies
49+
run: pnpm install
50+
51+
- name: Install Vale
52+
run: |
53+
wget -qO- https://github.com/errata-ai/vale/releases/download/v3.9.5/vale_3.9.5_Linux_64-bit.tar.gz | tar xz -C /usr/local/bin vale
54+
55+
- name: Sync Vale styles
56+
run: vale sync
57+
58+
- name: Run style review
59+
run: pnpm vale:review --pr ${{ github.event.pull_request.number || inputs.pr_number }}
60+
env:
61+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
62+
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
63+
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

‎.github/workflows/style-structural-review.yml‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
name: Structural Editorial Review
2+
3+
on:
4+
workflow_dispatch:
5+
inputs:
6+
pr_number:
7+
description: "Merged PR number to review"
8+
required: true
9+
type: number
10+
pull_request:
11+
types: [closed]
12+
paths:
13+
- "app/en/**/*.md"
14+
- "app/en/**/*.mdx"
15+
16+
permissions:
17+
contents: write
18+
pull-requests: write
19+
20+
jobs:
21+
editorial-review:
22+
name: Editorial Review
23+
runs-on: ubuntu-latest
24+
# Only run on merged PRs, skip editorial PRs to prevent loops
25+
if: |
26+
(github.event_name == 'workflow_dispatch' || github.event.pull_request.merged == true) &&
27+
!startsWith(github.head_ref || '', 'style/editorial-')
28+
29+
steps:
30+
- name: Checkout repository
31+
uses: actions/checkout@v4
32+
33+
- name: Use Node.js
34+
uses: actions/setup-node@v4
35+
with:
36+
node-version: "22.x"
37+
38+
- name: Install pnpm
39+
run: npm install -g pnpm
40+
41+
- name: Install dependencies
42+
run: pnpm install
43+
44+
- name: Install Vale
45+
run: |
46+
wget -qO- https://github.com/errata-ai/vale/releases/download/v3.9.5/vale_3.9.5_Linux_64-bit.tar.gz | tar xz -C /usr/local/bin vale
47+
48+
- name: Sync Vale styles
49+
run: vale sync
50+
51+
- name: Run editorial review
52+
run: pnpm vale:editorial --pr ${{ github.event.pull_request.number || inputs.pr_number }}
53+
env:
54+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
55+
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
56+
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

‎.gitignore‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,3 +16,8 @@ make_toolkit_docs/.env
1616
make_toolkit_docs/__pycache__/
1717
make_toolkit_docs/uv.lock
1818
*.bak
19+
20+
# Vale synced packages (re-sync with `vale sync`)
21+
styles/Google/
22+
styles/alex/
23+
styles/write-good/

‎.husky/pre-commit‎

Lines changed: 27 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,37 @@
1-
pnpm dlx lint-staged
2-
31
#!/bin/sh
42
# Exit on any error
53
set -e
64

75
# Check if there are any staged files
86
if [ -z "$(git diff --cached --name-only)" ]; then
9-
echo "No staged files to format"
7+
echo "No staged files to check"
108
exit 0
119
fi
1210

11+
# --- Vale Style Check ---
12+
# Check for staged .md/.mdx files
13+
STAGED_DOCS=$(git diff --cached --name-only --diff-filter=ACMR | grep -E '\.(md|mdx)$' || true)
14+
15+
if [ -n "$STAGED_DOCS" ]; then
16+
echo "🔍 Checking documentation style with Vale..."
17+
18+
# Run vale-fix script in staged mode (interactive)
19+
if [ -t 0 ]; then
20+
# Terminal is interactive - run the fix script
21+
pnpm vale:fix --staged
22+
else
23+
# Non-interactive (CI) - just run vale and report
24+
echo "$STAGED_DOCS" | xargs vale --output=line || {
25+
echo "⚠️ Vale found style issues. Run 'pnpm vale:fix <file>' to fix."
26+
# Don't block commit for style issues in CI, only toxic language
27+
# The GitHub Action (Option 1) will handle this later
28+
}
29+
fi
30+
fi
31+
32+
# --- Lint Staged (formatting) ---
33+
pnpm dlx lint-staged
34+
1335
# Store the hash of staged changes to detect modifications
1436
STAGED_HASH=$(git diff --cached | sha256sum | cut -d' ' -f1)
1537

@@ -36,10 +58,10 @@ if [ $STASHED -eq 0 ]; then
3658
fi
3759
done
3860
fi
39-
61+
4062
# Restore unstaged changes
4163
git stash pop --quiet || true
42-
64+
4365
# Restore partial staging if files were partially staged
4466
if [ -n "$PARTIALLY_STAGED" ]; then
4567
for file in $PARTIALLY_STAGED; do

‎.vale.ini‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# Vale configuration for Arcade docs
2+
# Using Google Developer Documentation Style Guide as base
3+
4+
StylesPath = styles
5+
6+
MinAlertLevel = suggestion
7+
8+
# Downloaded via `vale sync` - these go to styles/<Package>/
9+
Packages = Google, write-good, alex
10+
11+
# Project-specific vocabulary (committed to repo)
12+
Vocab = Arcade
13+
14+
[*.mdx]
15+
BasedOnStyles = Google, write-good, alex, Arcade
16+
17+
# Ignore code blocks, inline code, and className/class attributes
18+
BlockIgnores = (?s)```[\s\S]*?```
19+
TokenIgnores = (`[^`]+`|className="[^"]*"|className='[^']*'|class="[^"]*"|class='[^']*')
20+
21+
# --- Disable noisy/unhelpful rules ---
22+
23+
# Code-related false positives
24+
Google.Parens = NO
25+
Google.Spacing = NO
26+
Google.Quotes = NO
27+
28+
# JSX className attributes cause false positives (e.g., my-4, mx-2)
29+
Google.FirstPerson = NO
30+
31+
# Use Arcade.WordList instead (handles sentence-initial capitalization better)
32+
Google.WordList = NO
33+
34+
# Too strict for technical docs
35+
write-good.E-Prime = NO
36+
write-good.TooWordy = NO
37+
Google.Contractions = NO
38+
Google.Will = NO
39+
40+
# "execute" etc. flagged as profanity - not useful for tech docs
41+
alex.ProfanityUnlikely = NO
42+
43+
# "disabled" is valid in tech contexts (disabled buttons, disabled features)
44+
alex.Ablist = NO
45+
46+
# Ellipses are valid in code examples and UI text
47+
Google.Ellipses = NO
48+
49+
# Acronyms like API, SDK, MCP are standard in our docs
50+
Google.Acronyms = NO
51+
52+
# Disable duplicate passive voice rule (Google.Passive covers this)
53+
write-good.Passive = NO
54+
55+
# --- Keep enabled ---
56+
# Passive voice: Google.Passive
57+
# Toxic/harmful language checks (important!)
58+
# Good style rules (WordList, FirstPerson, We, Ellipses, Exclamation)
59+
60+
[*.md]
61+
BasedOnStyles = Google, write-good, alex, Arcade
62+
63+
# Ignore code blocks, inline code, and className/class attributes
64+
BlockIgnores = (?s)```[\s\S]*?```
65+
TokenIgnores = (`[^`]+`|className="[^"]*"|className='[^']*'|class="[^"]*"|class='[^']*')
66+
67+
# Same rules for .md files
68+
Google.Parens = NO
69+
Google.Spacing = NO
70+
Google.Quotes = NO
71+
Google.FirstPerson = NO
72+
Google.WordList = NO # Use Arcade.WordList instead
73+
write-good.E-Prime = NO
74+
write-good.TooWordy = NO
75+
Google.Contractions = NO
76+
Google.Will = NO
77+
alex.ProfanityUnlikely = NO
78+
alex.Ablist = NO
79+
Google.Ellipses = NO
80+
Google.Acronyms = NO
81+
write-good.Passive = NO

‎.vscode/settings.json‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -42,5 +42,6 @@
4242
"editor.codeActionsOnSave": {
4343
"source.fixAll.biome": "explicit",
4444
"source.organizeImports.biome": "explicit"
45-
}
46-
}
45+
},
46+
"makefile.configureOnOpen": false
47+
}

‎AGENTS.md‎

Lines changed: 69 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
# Agent Instructions
2+
3+
When working on documentation in this repo, follow the writing standards in [STYLEGUIDE.md](./STYLEGUIDE.md).
4+
5+
## Quick Reference
6+
7+
- Run `pnpm vale:check` to check all docs for style issues
8+
- Run `pnpm vale:fix <file>` to fix issues with AI assistance (optional, requires API key)
9+
- Run `pnpm vale:sync` to update Vale style packages
10+
11+
## Automated Style Reviews
12+
13+
This repo has automated style review workflows that run on PRs:
14+
15+
### Style Review (on PR open/update)
16+
17+
When you open or update a PR with changes to `app/en/**/*.md` or `app/en/**/*.mdx`, the style review workflow:
18+
19+
1. Runs Vale on changed files
20+
2. Sends issues to an LLM for suggested fixes
21+
3. Posts GitHub review comments with clickable "Apply suggestion" blocks
22+
23+
Each suggestion shows the Vale rule name (e.g., `Arcade.WordList`) and the fix. Authors can apply suggestions with one click or ignore them.
24+
25+
### Editorial Review (after merge)
26+
27+
After a PR is merged, the editorial review workflow:
28+
29+
1. Analyzes changed docs against [STYLEGUIDE.md](./STYLEGUIDE.md)
30+
2. If structural improvements are needed, creates a follow-up PR
31+
3. Assigns the follow-up PR to the original author
32+
33+
The follow-up PR contains document-level improvements like adding prerequisites sections or reorganizing content. Authors can accept, modify, or close it.
34+
35+
**Note:** Editorial PRs (branches starting with `style/editorial-`) skip both workflows to prevent loops.
36+
37+
## Local Development
38+
39+
### Setup
40+
41+
The scripts support both Anthropic (Claude) and OpenAI (GPT-4). Set either key in `.env.local`:
42+
43+
```bash
44+
# Option 1: Anthropic (preferred)
45+
ANTHROPIC_API_KEY=sk-ant-...
46+
47+
# Option 2: OpenAI
48+
OPENAI_API_KEY=sk-...
49+
```
50+
51+
If both keys are present, Anthropic is used by default.
52+
53+
### Commands
54+
55+
```bash
56+
pnpm vale:check # Check all docs for style issues
57+
pnpm vale:fix <file> # Interactive AI-powered fixes
58+
pnpm vale:review --pr N # Run style review locally on PR #N
59+
pnpm vale:editorial --pr N # Run editorial review locally on merged PR #N
60+
```
61+
62+
### Without an API Key
63+
64+
If you don't have an API key, `vale:fix` will still:
65+
- Run Vale and show you all style issues
66+
- Tell you which files have problems
67+
- Flag any toxic language issues that must be fixed
68+
69+
You can then fix issues manually using the detailed output from `vale <file>`.

0 commit comments

Comments
 (0)