|
| 1 | +#!/usr/bin/env bash |
| 2 | +# |
| 3 | +# Licensed to the Apache Software Foundation (ASF) under one |
| 4 | +# or more contributor license agreements. See the NOTICE file |
| 5 | +# distributed with this work for additional information |
| 6 | +# regarding copyright ownership. The ASF licenses this file |
| 7 | +# to you under the Apache License, Version 2.0 (the |
| 8 | +# "License"); you may not use this file except in compliance |
| 9 | +# with the License. You may obtain a copy of the License at |
| 10 | +# |
| 11 | +# http://www.apache.org/licenses/LICENSE-2.0 |
| 12 | +# |
| 13 | +# Unless required by applicable law or agreed to in writing, |
| 14 | +# software distributed under the License is distributed on an |
| 15 | +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| 16 | +# KIND, either express or implied. See the License for the |
| 17 | +# specific language governing permissions and limitations |
| 18 | +# under the License. |
| 19 | + |
| 20 | +# Regenerates the configuration and function documentation pages and checks |
| 21 | +# that the committed pages match, the same way the "check configs.md and |
| 22 | +# ***_functions.md is up-to-date" job does. With `--write`, replaces the pages |
| 23 | +# with the generated ones. |
| 24 | + |
| 25 | +set -euo pipefail |
| 26 | + |
| 27 | +SCRIPT_NAME="$(basename "${BASH_SOURCE[0]}")" |
| 28 | +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" |
| 29 | +ROOT_DIR="$(cd "${SCRIPT_DIR}/../.." && pwd)" |
| 30 | + |
| 31 | +source "${SCRIPT_DIR}/utils/git.sh" |
| 32 | + |
| 33 | +CONFIG_DOCS_DIR="docs/source/user-guide" |
| 34 | +FUNCTION_DOCS_DIR="docs/source/user-guide/sql" |
| 35 | + |
| 36 | +MODE="check" |
| 37 | +ALLOW_DIRTY=0 |
| 38 | + |
| 39 | +usage() { |
| 40 | + cat >&2 <<USAGE |
| 41 | +Usage: $0 [--write] [--allow-dirty] |
| 42 | +
|
| 43 | +Checks that docs/source/user-guide/configs.md and the aggregate, scalar, and window |
| 44 | +function pages under docs/source/user-guide/sql/ match the output of |
| 45 | +dev/update_config_docs.sh and dev/update_function_docs.sh. |
| 46 | +--write Replace the pages with the generated ones (requires a clean git worktree, no uncommitted changes). |
| 47 | +--allow-dirty Allow \`--write\` to run even when the git worktree has uncommitted changes. |
| 48 | +USAGE |
| 49 | + exit 1 |
| 50 | +} |
| 51 | + |
| 52 | +while [[ $# -gt 0 ]]; do |
| 53 | + case "$1" in |
| 54 | + --write) |
| 55 | + MODE="write" |
| 56 | + ;; |
| 57 | + --allow-dirty) |
| 58 | + ALLOW_DIRTY=1 |
| 59 | + ;; |
| 60 | + -h|--help) |
| 61 | + usage |
| 62 | + ;; |
| 63 | + *) |
| 64 | + usage |
| 65 | + ;; |
| 66 | + esac |
| 67 | + shift |
| 68 | +done |
| 69 | + |
| 70 | +cd "${ROOT_DIR}" |
| 71 | + |
| 72 | +if [[ "$MODE" == "write" && $ALLOW_DIRTY -eq 0 ]]; then |
| 73 | + require_clean_work_tree "$SCRIPT_NAME" || exit 1 |
| 74 | +fi |
| 75 | + |
| 76 | +if ! command -v npx >/dev/null 2>&1; then |
| 77 | + echo "[${SCRIPT_NAME}] npx is required to run the prettier check. Install Node.js (e.g., brew install node) and re-run." >&2 |
| 78 | + exit 1 |
| 79 | +fi |
| 80 | + |
| 81 | +# One scratch directory beneath each documentation directory, so Prettier finds |
| 82 | +# the same configuration as for the committed pages. |
| 83 | +SCRATCH_DIRS=() |
| 84 | +cleanup() { |
| 85 | + rm -rf ${SCRATCH_DIRS[@]+"${SCRATCH_DIRS[@]}"} |
| 86 | +} |
| 87 | +trap cleanup EXIT |
| 88 | +trap 'exit 130' INT |
| 89 | +trap 'exit 143' TERM |
| 90 | +CONFIG_SCRATCH="$(mktemp -d "${ROOT_DIR}/${CONFIG_DOCS_DIR}/.config-docs-check.XXXXXX")" |
| 91 | +SCRATCH_DIRS+=("${CONFIG_SCRATCH}") |
| 92 | +FUNCTION_SCRATCH="$(mktemp -d "${ROOT_DIR}/${FUNCTION_DOCS_DIR}/.function-docs-check.XXXXXX")" |
| 93 | +SCRATCH_DIRS+=("${FUNCTION_SCRATCH}") |
| 94 | + |
| 95 | +./dev/update_config_docs.sh --output-dir "${CONFIG_SCRATCH}" |
| 96 | +./dev/update_function_docs.sh --output-dir "${FUNCTION_SCRATCH}" |
| 97 | + |
| 98 | +GENERATED=( |
| 99 | + "${CONFIG_SCRATCH}/configs.md" |
| 100 | + "${FUNCTION_SCRATCH}/aggregate_functions.md" |
| 101 | + "${FUNCTION_SCRATCH}/scalar_functions.md" |
| 102 | + "${FUNCTION_SCRATCH}/window_functions.md" |
| 103 | +) |
| 104 | +COMMITTED=( |
| 105 | + "${CONFIG_DOCS_DIR}/configs.md" |
| 106 | + "${FUNCTION_DOCS_DIR}/aggregate_functions.md" |
| 107 | + "${FUNCTION_DOCS_DIR}/scalar_functions.md" |
| 108 | + "${FUNCTION_DOCS_DIR}/window_functions.md" |
| 109 | +) |
| 110 | + |
| 111 | +if [[ "$MODE" == "write" ]]; then |
| 112 | + for i in "${!COMMITTED[@]}"; do |
| 113 | + cp "${GENERATED[$i]}" "${COMMITTED[$i]}" || { |
| 114 | + echo "[${SCRIPT_NAME}] failed to copy the generated page to ${COMMITTED[$i]}" >&2 |
| 115 | + exit 1 |
| 116 | + } |
| 117 | + echo "✅ ${COMMITTED[$i]} updated." |
| 118 | + done |
| 119 | + exit 0 |
| 120 | +fi |
| 121 | + |
| 122 | +stale_count=0 |
| 123 | +for i in "${!COMMITTED[@]}"; do |
| 124 | + diff_status=0 |
| 125 | + diff -u -L "${COMMITTED[$i]} (committed)" -L "${COMMITTED[$i]} (generated)" \ |
| 126 | + "${COMMITTED[$i]}" "${GENERATED[$i]}" > "${GENERATED[$i]}.diff" || diff_status=$? |
| 127 | + case "${diff_status}" in |
| 128 | + 0) |
| 129 | + echo "✅ ${COMMITTED[$i]} is up-to-date." |
| 130 | + ;; |
| 131 | + 1) |
| 132 | + stale_count=$((stale_count + 1)) |
| 133 | + echo "" |
| 134 | + echo "❌ ${COMMITTED[$i]} is out of date." |
| 135 | + echo "------------------------------------------------------------" |
| 136 | + cat "${GENERATED[$i]}.diff" |
| 137 | + echo "------------------------------------------------------------" |
| 138 | + ;; |
| 139 | + *) |
| 140 | + echo "❌ diff exited with status ${diff_status} while comparing ${COMMITTED[$i]}; no comparison result." >&2 |
| 141 | + exit "${diff_status}" |
| 142 | + ;; |
| 143 | + esac |
| 144 | +done |
| 145 | + |
| 146 | +if [[ ${stale_count} -gt 0 ]]; then |
| 147 | + echo "" |
| 148 | + echo "${stale_count} generated page(s) out of date. To update them, run:" |
| 149 | + echo "" |
| 150 | + echo " ./ci/scripts/check_generated_docs.sh --write" |
| 151 | + exit 1 |
| 152 | +fi |
0 commit comments