From 017cebc06b9901bd2caf8a34cf2ddd9b5879a34b Mon Sep 17 00:00:00 2001 From: Joe McIlvain Date: Wed, 5 Jun 2024 13:02:07 -0700 Subject: [PATCH] chore: interpolate example code in README.md for each package 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. --- .github/workflows/ci.yaml | 3 ++ package.json | 1 + packages/kurt-open-ai/README.md | 2 +- packages/kurt-open-ai/package.json | 1 + packages/kurt-vertex-ai/README.md | 2 +- packages/kurt-vertex-ai/package.json | 1 + packages/kurt/package.json | 1 + scripts/interpolate-example-code.sh | 49 ++++++++++++++++++++++++++++ turbo.json | 3 +- 9 files changed, 60 insertions(+), 3 deletions(-) create mode 100755 scripts/interpolate-example-code.sh diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index b930852..1b29db6 100644 --- a/.github/workflows/ci.yaml +++ b/.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: diff --git a/package.json b/package.json index e7e0515..b99988b 100644 --- a/package.json +++ b/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 --" } } diff --git a/packages/kurt-open-ai/README.md b/packages/kurt-open-ai/README.md index c653254..249427b 100644 --- a/packages/kurt-open-ai/README.md +++ b/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. diff --git a/packages/kurt-open-ai/package.json b/packages/kurt-open-ai/package.json index a4278b8..84e8da4 100644 --- a/packages/kurt-open-ai/package.json +++ b/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": { diff --git a/packages/kurt-vertex-ai/README.md b/packages/kurt-vertex-ai/README.md index c57dfc6..91198ab 100644 --- a/packages/kurt-vertex-ai/README.md +++ b/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. diff --git a/packages/kurt-vertex-ai/package.json b/packages/kurt-vertex-ai/package.json index 332ee31..f1b4f87 100644 --- a/packages/kurt-vertex-ai/package.json +++ b/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": { diff --git a/packages/kurt/package.json b/packages/kurt/package.json index e0e6951..aca1a4d 100644 --- a/packages/kurt/package.json +++ b/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": { diff --git a/scripts/interpolate-example-code.sh b/scripts/interpolate-example-code.sh new file mode 100755 index 0000000..8247398 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/turbo.json b/turbo.json index 928e181..5a0f65a 100644 --- a/turbo.json +++ b/turbo.json @@ -15,6 +15,7 @@ }, "check": {}, "format": {}, - "lint": {} + "lint": {}, + "prepublish": {} } }