From 2a2c49424d7ec032c08d7d4759ac70dd04cd1bd7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Muzyk?= Date: Fri, 27 Mar 2026 10:57:33 +0100 Subject: [PATCH 1/4] feat: Validate API docs --- .github/scripts/verifyDocs.sh | 24 ++++++++++++++++++++++++ .github/workflows/validateDocs.yml | 26 ++++++++++++++++++++++++++ 2 files changed, 50 insertions(+) create mode 100755 .github/scripts/verifyDocs.sh create mode 100644 .github/workflows/validateDocs.yml diff --git a/.github/scripts/verifyDocs.sh b/.github/scripts/verifyDocs.sh new file mode 100755 index 000000000..5c5f32e60 --- /dev/null +++ b/.github/scripts/verifyDocs.sh @@ -0,0 +1,24 @@ +#!/bin/bash +# +# Re-generates API docs and verifies that there is no diff, +# because that would indicate that the PR author forgot to run `npm run build:docs` +# and commit the updated API.md and API-INTERNAL.md files. + +declare -r GREEN='\033[0;32m' +declare -r RED='\033[0;31m' +declare -r NC='\033[0m' + +printf '\nRebuilding API docs...\n' +npm run build:docs + +DIFF_OUTPUT=$(git diff --exit-code API.md API-INTERNAL.md) +EXIT_CODE=$? + +if [[ EXIT_CODE -eq 0 ]]; then + echo -e "${GREEN}API docs are up to date!${NC}" + exit 0 +else + echo -e "${RED}Error: Diff found when API docs were rebuilt. Did you forget to run \`npm run build:docs\` after making changes?${NC}" + echo "$DIFF_OUTPUT" + exit 1 +fi diff --git a/.github/workflows/validateDocs.yml b/.github/workflows/validateDocs.yml new file mode 100644 index 000000000..c4d9c472f --- /dev/null +++ b/.github/workflows/validateDocs.yml @@ -0,0 +1,26 @@ +name: Validate API Docs + +on: + pull_request: + types: [opened, synchronize] + paths: ['lib/**', 'buildDocs.ts', 'API.md', 'API-INTERNAL.md'] + +jobs: + verify: + runs-on: ubuntu-latest + steps: + # v5.0.0 + - uses: actions/checkout@ff7abcd0c3c05ccf6adc123a8cd1fd4fb30fb493 + + - name: Setup Node + # v4.4.0 + uses: actions/setup-node@cdca7365b2dadb8aad0a33bc7601856ffabcc48e + with: + node-version-file: ".nvmrc" + cache: npm + cache-dependency-path: package-lock.json + + - run: npm ci + + - name: Verify API Docs Are Up To Date + run: ./.github/scripts/verifyDocs.sh From 4fb9389bf8317ba0be1df524277c66487a7223eb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Muzyk?= Date: Fri, 27 Mar 2026 11:40:09 +0100 Subject: [PATCH 2/4] test - should fail --- API.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/API.md b/API.md index 545adbfab..bf3ee5db1 100644 --- a/API.md +++ b/API.md @@ -6,7 +6,7 @@
init()
-

Initialize the store with actions and listening for storage events

+

Initialize the store with actions and listening for storage events events events

connect(connectOptions) ⇒

Connects to an Onyx key given the options passed and listens to its changes. From ab8c9664ca10d496c6876c0165101f803301368b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Muzyk?= Date: Fri, 27 Mar 2026 11:41:36 +0100 Subject: [PATCH 3/4] test - should pass --- API.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/API.md b/API.md index bf3ee5db1..545adbfab 100644 --- a/API.md +++ b/API.md @@ -6,7 +6,7 @@

init()
-

Initialize the store with actions and listening for storage events events events

+

Initialize the store with actions and listening for storage events

connect(connectOptions) ⇒

Connects to an Onyx key given the options passed and listens to its changes. From c210fb2765ab628e7a02327d43beb834a89372f4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Micha=C5=82=20Muzyk?= Date: Fri, 27 Mar 2026 12:03:23 +0100 Subject: [PATCH 4/4] fix: improvements --- .github/scripts/verifyDocs.sh | 5 ++++- .github/workflows/validateDocs.yml | 2 +- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/.github/scripts/verifyDocs.sh b/.github/scripts/verifyDocs.sh index 5c5f32e60..ae32b0e81 100755 --- a/.github/scripts/verifyDocs.sh +++ b/.github/scripts/verifyDocs.sh @@ -9,7 +9,10 @@ declare -r RED='\033[0;31m' declare -r NC='\033[0m' printf '\nRebuilding API docs...\n' -npm run build:docs +if ! npm run build:docs; then + echo -e "${RED}Error: \`npm run build:docs\` failed. Please fix the build errors before continuing.${NC}" + exit 1 +fi DIFF_OUTPUT=$(git diff --exit-code API.md API-INTERNAL.md) EXIT_CODE=$? diff --git a/.github/workflows/validateDocs.yml b/.github/workflows/validateDocs.yml index c4d9c472f..43fdf9630 100644 --- a/.github/workflows/validateDocs.yml +++ b/.github/workflows/validateDocs.yml @@ -3,7 +3,7 @@ name: Validate API Docs on: pull_request: types: [opened, synchronize] - paths: ['lib/**', 'buildDocs.ts', 'API.md', 'API-INTERNAL.md'] + paths: ['lib/**', 'buildDocs.ts', 'API.md', 'API-INTERNAL.md', '.github/workflows/validateDocs.yml', '.github/scripts/verifyDocs.sh'] jobs: verify: