Skip to content

Commit b5f0cec

Browse files
lucasfcostalucasfcosta
authored
feat: automatically update docs on SDK changes (#767)
1 parent 81eedde commit b5f0cec

File tree

1 file changed

+164
-0
lines changed

1 file changed

+164
-0
lines changed

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

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
name: Update Documentation
2+
3+
on:
4+
push:
5+
branches:
6+
- main
7+
paths:
8+
- 'src/**/*.ts'
9+
10+
jobs:
11+
update-docs:
12+
runs-on: ubuntu-latest
13+
name: Trigger Mintlify Agent
14+
if: github.repository == 'resend/resend-node'
15+
permissions:
16+
contents: read
17+
18+
steps:
19+
- name: Checkout code
20+
uses: actions/checkout@v4
21+
with:
22+
fetch-depth: 0
23+
24+
- name: Call Mintlify Agent API
25+
env:
26+
MINTLIFY_API_KEY: ${{ secrets.MINTLIFY_API_KEY }}
27+
MINTLIFY_PROJECT_ID: ${{ secrets.MINTLIFY_PROJECT_ID }}
28+
COMMITS_JSON: ${{ toJson(github.event.commits) }}
29+
COMMIT_SHA: ${{ github.sha }}
30+
COMMIT_AUTHOR: ${{ github.actor }}
31+
GITHUB_REPOSITORY: ${{ github.repository }}
32+
GITHUB_REF_NAME: ${{ github.ref_name }}
33+
run: |
34+
echo "Triggering Mintlify agent to update documentation..."
35+
36+
# Get information about all commits in this push
37+
COMMIT_URL="https://github.com/${GITHUB_REPOSITORY}/commit/${COMMIT_SHA}"
38+
TIMESTAMP=$(date +%s)
39+
40+
# If no commits in event (manual trigger), fall back to latest commit
41+
if [ "$COMMITS_JSON" == "null" ] || [ "$COMMITS_JSON" == "" ]; then
42+
echo "No commits in push event, using HEAD commit"
43+
COMMIT_MESSAGE=$(git log -1 --pretty=%B)
44+
# Use jq to properly escape the commit message
45+
COMMITS_JSON=$(jq -n \
46+
--arg id "${COMMIT_SHA}" \
47+
--arg message "${COMMIT_MESSAGE}" \
48+
--arg author "${COMMIT_AUTHOR}" \
49+
'[{id: $id, message: $message, author: $author}]')
50+
else
51+
COMMIT_COUNT=$(echo "$COMMITS_JSON" | jq '. | length')
52+
echo "Processing ${COMMIT_COUNT} commit(s) from this push"
53+
fi
54+
55+
# Build context message with commit details
56+
CONTEXT_MESSAGE="Update documentation for recent changes to the Resend Node.js SDK pushed to ${GITHUB_REPOSITORY} on branch ${GITHUB_REF_NAME}.
57+
58+
Repository: ${GITHUB_REPOSITORY}
59+
Branch: ${GITHUB_REF_NAME}
60+
Commit: ${COMMIT_URL}
61+
Pushed by: ${COMMIT_AUTHOR}
62+
63+
Commits in this push:
64+
$(echo "$COMMITS_JSON" | jq -r '.[] | "- \(.id[0:7]): \(.message | split("\n")[0])"')
65+
66+
Please analyze these changes to the Node.js SDK and update the documentation accordingly **if they're customer-facing changes**.
67+
68+
In the vast majority of times, you will only have to update the API reference documentation and code examples for the Node.js SDK if not already up to date.
69+
70+
If these changes do not impact the public API or user experience, no documentation updates are necessary.
71+
72+
You don't need to document internal implementation details unless they affect how users interact with the SDK.
73+
74+
Avoid unnecessary updates; focus only on relevant changes. Examples of relevant changes include:
75+
76+
- New or modified SDK methods or interfaces
77+
- Changes to method parameters or return types
78+
- Updated usage instructions or examples
79+
- New features or deprecations
80+
- Changes in required dependencies or peer dependencies
81+
- Updates to TypeScript types that affect developer experience
82+
83+
Ensure that any documentation updates are clear, concise, and follow the existing style and format of the documentation.
84+
85+
IMPORTANT: It's extremely important that you follow the naming conventions for PRs:
86+
- <feat|fix|chore>: <concise description of the change>
87+
88+
IMPORTANT: If these changes are already documented the target docs repo, you can just skip creating a PR altogether."
89+
90+
# Build the request body with proper Mintlify API schema
91+
# Customize the SYSTEM_PROMPT below with your documentation guidelines
92+
SYSTEM_PROMPT="You are an AI agent that updates Resend's documentation.
93+
94+
IMPORTANT: When you create a pull request, format the title using conventional commits:
95+
- Use 'feat:' prefix for new features or additions
96+
- Use 'fix:' prefix for bug fixes or corrections
97+
- Use 'chore:' prefix for maintenance tasks, refactoring, or minor updates
98+
Example: 'feat: add new broadcast methods to Node.js SDK examples'
99+
100+
Guidelines:
101+
- Be concise and clear. Avoid long-winded explanations and focus on how changes impact users.
102+
- When modifying the API reference, ensure accuracy in method signatures, parameters, and response types.
103+
- Make sure to update the code examples in the API reference if there are changes to the Node.js SDK usage patterns.
104+
- If a field is optional, it does _not_ need to be included in the example, but it should be presented in the parameter list.
105+
- Use proper formatting for code snippets (TypeScript/JavaScript for Node.js SDK examples).
106+
- Prioritize user-facing changes that impact how developers interact with the SDK. If a change is only internal and does not affect users, no documentation update is needed. It's as important to avoid unnecessary updates as it is to add new information to avoid overloading users with irrelevant details.
107+
- The vast majority of time, your changes will happen to the API reference documentation code examples, but it might be the case that you also need to update code snippets in integration guides. You will _rarely_ have to update knowledge base articles' text and explanations, but that might happen. Still, be mindful and extra critical about whether a change is necessary in those cases.
108+
- Focus on Node.js/TypeScript SDK examples. When updating API reference docs, ensure the Node.js SDK tab shows the correct usage.
109+
- Remember: You don't need to update the SDK examples when there's a new _optional_ parameter added to a method. The SDK examples should focus on the most common usage patterns, so optional parameters can be omitted.
110+
111+
When analyzing changes:
112+
- Identify new or modified SDK methods, interfaces, and types
113+
- Determine whether the changes impact user experience or SDK usage (e.g., new features, changes in method signatures, new TypeScript types)
114+
- Have a look at the existing documentation to understand the existing style and format
115+
- Ensure you're not introducing redundant or unnecessary information
116+
- Make sure to update the code examples if there are changes to SDK usage patterns
117+
- Pay special attention to TypeScript type definitions as they affect the developer experience
118+
119+
Based on your analysis, update the documentation files in the repository accordingly."
120+
121+
REQUEST_BODY=$(jq -n \
122+
--arg branch "mintlify/docs-update-${TIMESTAMP}" \
123+
--arg system "$SYSTEM_PROMPT" \
124+
--arg context "$CONTEXT_MESSAGE" \
125+
'{
126+
branch: $branch,
127+
messages: [
128+
{
129+
role: "system",
130+
content: $system
131+
},
132+
{
133+
role: "user",
134+
content: $context
135+
}
136+
]
137+
}')
138+
139+
# Call Mintlify Agent API with correct endpoint and schema
140+
echo "Calling Mintlify API endpoint..."
141+
RESPONSE=$(curl -X POST "https://api.mintlify.com/v1/agent/${MINTLIFY_PROJECT_ID}/job" \
142+
-H "Authorization: Bearer ${MINTLIFY_API_KEY}" \
143+
-H "Content-Type: application/json" \
144+
-d "$REQUEST_BODY" \
145+
-w "\n%{http_code}" \
146+
-s)
147+
148+
# Extract response body and status code
149+
HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
150+
RESPONSE_BODY=$(echo "$RESPONSE" | head -n-1)
151+
152+
echo "Response: $RESPONSE_BODY"
153+
echo "HTTP Status: $HTTP_CODE"
154+
155+
# Check for success (2xx status codes)
156+
if [[ "$HTTP_CODE" =~ ^2 ]]; then
157+
echo "✅ Successfully triggered Mintlify agent"
158+
echo "The agent will analyze these changes and create a PR in resend-docs if documentation updates are needed."
159+
else
160+
echo "❌ Failed to trigger Mintlify agent"
161+
echo "Please check your MINTLIFY_API_KEY and MINTLIFY_PROJECT_ID secrets"
162+
echo "Error response: $RESPONSE_BODY"
163+
exit 1
164+
fi

0 commit comments

Comments
 (0)