Skip to content

Commit 9600fe3

Browse files
darrenmelvison1proletesseract
darrenmelvison1
and
proletesseract
authored
feat(examples): DVR-330 | Dynamic Prompts to create tutorial/metadata of example apps and CI/CD workflow (#2585)
Co-authored-by: Craig M. <[email protected]>
1 parent 7123bee commit 9600fe3

File tree

64 files changed

+4255
-2
lines changed

Some content is hidden

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

64 files changed

+4255
-2
lines changed

‎.github/scripts/process-tutorials.sh

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
#!/bin/bash
2+
3+
set -e
4+
set -x
5+
6+
# Directory where docs repo is cloned (should match push-docs.sh)
7+
DOCS_REPO_DIR=${CLONE_DIR:-"./imx-docs"}
8+
9+
# Root of the example apps
10+
EXAMPLES_ROOT="./examples"
11+
12+
# Products to process
13+
PRODUCTS=("passport" "checkout" "orderbook" "contracts")
14+
15+
# Process tutorials for each product
16+
for PRODUCT in "${PRODUCTS[@]}"; do
17+
echo "Processing tutorials for $PRODUCT..."
18+
19+
# Create _tutorials directory in docs repo if it doesn't exist
20+
TUTORIALS_DIR="$DOCS_REPO_DIR/docs/main/example/zkEVM/$PRODUCT-examples/_tutorials"
21+
mkdir -p "$TUTORIALS_DIR"
22+
23+
# Get all example apps for this product
24+
SAMPLE_APPS=$(ls -d $EXAMPLES_ROOT/$PRODUCT/*/ 2>/dev/null | xargs -n1 basename)
25+
26+
for APP in $SAMPLE_APPS; do
27+
TUTORIAL_FILE="$EXAMPLES_ROOT/$PRODUCT/$APP/tutorial.md"
28+
29+
# Check if tutorial.md exists
30+
if [ -f "$TUTORIAL_FILE" ]; then
31+
echo "Processing tutorial for $APP..."
32+
33+
# Copy the content to a new file named after the app
34+
cp "$TUTORIAL_FILE" "$TUTORIALS_DIR/${APP}.md"
35+
echo "Copied $TUTORIAL_FILE to $TUTORIALS_DIR/${APP}.md"
36+
else
37+
echo "No tutorial.md found for $APP, skipping..."
38+
fi
39+
done
40+
41+
# Also copy the generated JSON file
42+
JSON_FILE="$EXAMPLES_ROOT/_parsed/${PRODUCT}-examples.json"
43+
if [ -f "$JSON_FILE" ]; then
44+
# Create directory for JSON file if it doesn't exist
45+
JSON_DIR="$DOCS_REPO_DIR/docs/main/example/zkEVM/$PRODUCT-examples"
46+
mkdir -p "$JSON_DIR"
47+
48+
# Copy JSON file
49+
cp "$JSON_FILE" "$JSON_DIR/${PRODUCT}-examples.json"
50+
echo "Copied $JSON_FILE to $JSON_DIR/${PRODUCT}-examples.json"
51+
else
52+
echo "Warning: No ${PRODUCT}-examples.json found at $JSON_FILE"
53+
fi
54+
done
55+
56+
echo "Tutorial processing complete."

‎.github/workflows/publish-example-tutorials.yaml

Lines changed: 78 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,78 @@
1+
name: Publish Example App Tutorials
2+
3+
on:
4+
# Run when changes are pushed to example tutorials or metadata
5+
push:
6+
branches:
7+
- main
8+
paths:
9+
- 'examples/*/*/tutorial.md'
10+
- 'examples/*/*/metadata.json'
11+
# Allow manual triggering
12+
workflow_dispatch:
13+
14+
concurrency:
15+
group: example-tutorials
16+
cancel-in-progress: false
17+
18+
jobs:
19+
PublishExampleTutorials:
20+
name: Process and Publish Example Tutorials
21+
runs-on: ubuntu-latest
22+
steps:
23+
- name: Checkout SDK Repo
24+
uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
25+
with:
26+
fetch-depth: 0
27+
ref: main
28+
29+
- name: Checkout Docs Repo
30+
uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
31+
with:
32+
repository: immutable/docs
33+
token: ${{ secrets.TS_IMMUTABLE_SDK_GITHUB_TOKEN }}
34+
path: imx-docs
35+
ref: main
36+
37+
- name: Setup environment variables
38+
run: |
39+
echo "CLONE_DIR=./imx-docs" >> $GITHUB_ENV
40+
41+
- name: Setup Github
42+
run: |
43+
git config --global user.name "${GITHUB_ACTOR}"
44+
git config --global user.email "${GITHUB_ACTOR}@users.noreply.github.com"
45+
46+
- name: setup
47+
uses: ./.github/actions/setup
48+
49+
- name: Install Dependencies
50+
run: pnpm install --frozen-lockfile
51+
52+
- name: Process Example App Tutorials
53+
run: |
54+
# Generate example app JSON files
55+
pnpm parse:examples
56+
57+
# Process tutorials and copy to docs repo
58+
./.github/scripts/process-tutorials.sh
59+
shell: bash
60+
61+
- name: Commit and Push Changes to Docs Repo
62+
run: |
63+
cd "$CLONE_DIR"
64+
# Check if there are changes to commit
65+
if git status --porcelain | grep -q .; then
66+
# Add all changes
67+
git add .
68+
69+
# Commit the changes
70+
git commit -m "Update example app tutorials from SDK repo"
71+
72+
# Push to the target branch
73+
git push -u origin main
74+
echo "Successfully pushed example app tutorial changes to docs repo"
75+
else
76+
echo "No changes to commit"
77+
fi
78+
shell: bash

‎examples/README.md

Lines changed: 27 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,8 @@
2222
- [Adding examples](#adding-examples)
2323
- [End to end testing](#end-to-end-testing)
2424
- [Using code examples in the docs site](#using-code-examples-in-the-docs-site)
25+
- [Generating Tutorials and Metadata](#generating-tutorials-and-metadata)
26+
2527
<hr />
2628

2729
# Introduction
@@ -412,4 +414,28 @@ You can now double check the code snippets in your `docs` branch are all pulling
412414

413415
Once your `docs` PR is merged, Netlify should automatically build and deploy the docs site. If your updates are not reflected on the docs site within 10 minutes of the PR being merged, it's likely the build has failed in Netlify. Because we are now pulling in content dynamically for the code snippets, the GET requests to fetch the code examples can sometimes randomly timeout which fails the build.
414416

415-
If this happens you will need to log into the Netlify site, check the error and retry the build. Usually this will fix the deployment issue, otherwise follow up on the error message shown by Netlify.
417+
If this happens you will need to log into the Netlify site, check the error and retry the build. Usually this will fix the deployment issue, otherwise follow up on the error message shown by Netlify.
418+
419+
# Generating Tutorials and Metadata
420+
421+
Whenever you add a new example app, or update an existing example app, you can use the prompts in the `prompt.txt` files in each `examples/product` folder to generate the tutorials and metadata for the example apps using Cursor AI.
422+
423+
These AI generated tutorials and metadata files are then piped through to the docs site in the CI/CD pipeline, where they are used to display the example apps and their code walkthroughs. If you don't follow these steps, your example app will not be displayed on the docs site.
424+
425+
There is a single prompt for each product as we expect the examples to follow a similar structure and format, therefore the prompt to generate the tutorials and metadata is the same for each product. You can specify which example app you want the prompt to generate the tutorials and metadata for by adding the app name to the prompt as shown below.
426+
427+
These prompts are designed to be used with Cursor IDE Composer Agent mode.
428+
429+
Follow these steps to generate the tutorials and metadata for the example apps:
430+
431+
1. Delete the existing tutorial.md and metadata.json files in the example app you are wanting to generate the tutorials and metadata for.
432+
2. Open the Composer window in Cursor IDE (Claude 3.7-sonnet-thinking).
433+
3. Press the `+` button clear the context of the composer window.
434+
4. Open the `prompt.txt` file in the examples/product folder you are wanting to generate the tutorials and metadata for e.g. `examples/passport/prompt.txt`.
435+
5. Copy and pate the prompt into the composer window, or attach it as a file.
436+
6. After adding the prompt, in the composer window, type `app name: <name of the example app>` e.g. `app name: login-with-nextjs` where the app name is the folder name of the example app in the examples/product folder you are wanting to generate the tutorials and metadata for.
437+
7. Press enter and let the AI generate the tutorials and metadata.
438+
8. Review the generated tutorials and metadata.
439+
9. If you're happy with the generated tutorials and metadata, you can commit and push the changes to your branch in the `ts-immutable-sdk` repo.
440+
441+
Once you have merged your branch into main, the tutorials and metadata will be automatically piped to the docs site and displayed in the example apps section.

‎examples/_parsed/checkout-examples.json

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,98 @@
1+
{
2+
"sdk-connect-with-nextjs": {
3+
"tutorial": "sdk-connect-with-nextjs.md",
4+
"metadata": {
5+
"title": "Connect with MetaMask in Next.js",
6+
"description": "A Next.js example that demonstrates how to integrate the Immutable Checkout SDK to connect with MetaMask wallets, with and without explicit permissions",
7+
"keywords": [
8+
"Immutable",
9+
"SDK",
10+
"Checkout",
11+
"Wallet",
12+
"MetaMask",
13+
"Connect",
14+
"Next.js"
15+
],
16+
"tech_stack": [
17+
"Next.js",
18+
"TypeScript",
19+
"React",
20+
"ethers.js"
21+
],
22+
"product": "Checkout",
23+
"programming_language": "TypeScript",
24+
"sidebar_order": 1
25+
}
26+
},
27+
"sdk-gas-estimation-with-nextjs": {
28+
"tutorial": "sdk-gas-estimation-with-nextjs.md",
29+
"metadata": {
30+
"title": "Gas Estimation with Checkout SDK and Next.js",
31+
"description": "Example app demonstrating how to estimate gas fees for swap and bridge transactions using the Immutable Checkout SDK",
32+
"keywords": [
33+
"Immutable",
34+
"SDK",
35+
"Gas Estimation",
36+
"Swap",
37+
"Bridge",
38+
"Layer 2",
39+
"MetaMask"
40+
],
41+
"tech_stack": [
42+
"Next.js",
43+
"React",
44+
"TypeScript",
45+
"Ethers.js"
46+
],
47+
"product": "Checkout",
48+
"programming_language": "TypeScript",
49+
"sidebar_order": 2
50+
}
51+
},
52+
"sdk-switch-network-with-nextjs": {
53+
"tutorial": "sdk-switch-network-with-nextjs.md",
54+
"metadata": {
55+
"title": "Switch Network with MetaMask using Next.js",
56+
"description": "An example app demonstrating how to connect to MetaMask and switch between Ethereum networks using the Immutable Checkout SDK",
57+
"keywords": [
58+
"Immutable",
59+
"SDK",
60+
"MetaMask",
61+
"Network Switching",
62+
"Checkout",
63+
"Wallet Connection"
64+
],
65+
"tech_stack": [
66+
"Next.js",
67+
"TypeScript",
68+
"React",
69+
"Ethers.js"
70+
],
71+
"product": "Checkout",
72+
"programming_language": "TypeScript",
73+
"sidebar_order": 3
74+
}
75+
},
76+
"sdk-wallet-balance-with-nextjs": {
77+
"tutorial": "sdk-wallet-balance-with-nextjs.md",
78+
"metadata": {
79+
"title": "Wallet Balance with NextJS",
80+
"description": "Example app demonstrating how to check wallet balances using the Immutable Checkout SDK with NextJS",
81+
"keywords": [
82+
"Immutable",
83+
"SDK",
84+
"Checkout",
85+
"Wallet Balance",
86+
"MetaMask"
87+
],
88+
"tech_stack": [
89+
"NextJS",
90+
"TypeScript",
91+
"React"
92+
],
93+
"product": "Checkout",
94+
"programming_language": "TypeScript",
95+
"sidebar_order": 2
96+
}
97+
}
98+
}

‎examples/_parsed/contracts-examples.json

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,25 @@
1+
{
2+
"contract-interaction-with-viem": {
3+
"tutorial": "contract-interaction-with-viem.md",
4+
"metadata": {
5+
"title": "Contract Interaction with Viem",
6+
"description": "Example demonstrating how to interact with Immutable ERC721 contracts using Viem, focusing on batch minting capabilities by token ID and quantity.",
7+
"keywords": [
8+
"Immutable",
9+
"SDK",
10+
"Contracts",
11+
"ERC721",
12+
"Batch Minting",
13+
"Viem",
14+
"zkEVM"
15+
],
16+
"tech_stack": [
17+
"TypeScript",
18+
"Viem",
19+
"Immutable Contracts"
20+
],
21+
"product": "Contracts",
22+
"programming_language": "TypeScript"
23+
}
24+
}
25+
}

0 commit comments

Comments
 (0)