diff --git a/.github/scripts/verifyDocs.sh b/.github/scripts/verifyDocs.sh new file mode 100755 index 000000000..ae32b0e81 --- /dev/null +++ b/.github/scripts/verifyDocs.sh @@ -0,0 +1,27 @@ +#!/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' +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=$? + +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..43fdf9630 --- /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', '.github/workflows/validateDocs.yml', '.github/scripts/verifyDocs.sh'] + +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