Merge pull request #40 from FormulaMonks/chore/interpolate-example-co…

…de-in-readmes

chore: interpolate example code in README.md for each package

.github/workflows/ci.yaml

@@ -34,6 +34,9 @@ jobs:
       - run: pnpm install --no-frozen-lockfile
       - run: pnpm run test
 
+      # Validate that the prepublish hook works.
+      - run: pnpm run prepublish
+
       # Finally, release (actual publishing only happens on the main branch).
       - run: pnpm run release
         env:

package.json

@@ -21,6 +21,7 @@
     "check": "pnpm turbo check",
     "lint": "pnpm turbo lint",
     "format": "pnpm turbo format",
+    "prepublish": "pnpm turbo prepublish",
     "release": "pnpm run -r --workspace-concurrency 1 release --"
   }
 }

packages/kurt-open-ai/README.md

@@ -8,4 +8,4 @@ This package implements an adapter for Kurt that works with [OpenAI's GPT models
 
 ## Examples
 
-Check the [example folder](https://github.com/FormulaMonks/kurt/tree/main/examples)
+[This example code](../../examples/basic/src/openai.ts) shows how to set up and use Kurt with OpenAI.

packages/kurt-open-ai/package.json

@@ -19,6 +19,7 @@
     "format": "pnpm biome format --write .",
     "lint": "pnpm biome lint --apply .",
     "check": "pnpm biome check .",
+    "prepublish": "../../scripts/interpolate-example-code.sh README.md",
     "release": "pnpm exec semantic-release"
   },
   "release": {

packages/kurt-vertex-ai/README.md

@@ -8,4 +8,4 @@ This package implements an adapter for Kurt that works with [Vertex AI's Gemini
 
 ## Examples
 
-Check the [example folder](https://github.com/FormulaMonks/kurt/tree/main/examples)
+[This example code](../../examples/basic/src/vertex.ts) shows how to set up and use Kurt with Vertex AI.

packages/kurt-vertex-ai/package.json

@@ -19,6 +19,7 @@
     "format": "pnpm biome format --write .",
     "lint": "pnpm biome lint --apply .",
     "check": "pnpm biome check .",
+    "prepublish": "../../scripts/interpolate-example-code.sh README.md",
     "release": "pnpm exec semantic-release"
   },
   "release": {

packages/kurt/package.json

@@ -19,6 +19,7 @@
     "format": "pnpm biome format --write .",
     "lint": "pnpm biome lint --apply .",
     "check": "pnpm biome check .",
+    "prepublish": "../../scripts/interpolate-example-code.sh README.md",
     "release": "pnpm exec semantic-release"
   },
   "release": {

scripts/interpolate-example-code.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+
+set -euo pipefail
+
+# This script will modify the given files (all CLI arguments passed to the
+# script are interpreted as filenames) to interpolate example code from files.
+#
+# It looks for lines that look like this:
+#
+# [This example code](../path/to/file.ts) shows how to do X.
+#
+# And replaces those occurrences to look like this:
+#
+# This example code shows how to do X.
+#
+# ```ts
+# // Contents of ../path/to/file.ts
+# ```
+#
+# This simple hack allows us to keep our code examples in separate files
+# (which are runnable and testable in CI), while still including them inline in
+# the documentation that gets published to npmjs.org for the packages.
+
+for file in "${@}"; do
+  echo "Interpolating example code in $file"
+
+  IFS=''
+  while read -r line; do
+    if echo "$line" | grep -E '\[This example code\]\([^)]+\).+$' > /dev/null; then
+      # If the line contains the pattern indicating a code example, fetch
+      # the code and print it as a markdown code block.
+      file_path=$(echo $line | cut -d '(' -f 2 | cut -d ')' -f 1)
+      file_code=$(cat $file_path)
+
+      # Print the line without the code link, followed by the code block.
+      printf "This example code"; echo "$line" | cut -d ')' -f 2-
+      echo # Empty line before the snippet
+      echo '```ts'
+      cat $file_path
+      echo '```'
+    else
+      # For all lines which don't match the pattern, print them as-is.
+      echo "$line"
+    fi
+  done < "$file" > "$file.tmp"
+  mv "$file.tmp" "$file"
+
+  git diff --color "$file" | cat
+done

turbo.json

@@ -15,6 +15,7 @@
     },
     "check": {},
     "format": {},
-    "lint": {}
+    "lint": {},
+    "prepublish": {}
   }
 }