chore: import upstream snapshot with attribution
This commit is contained in:
wehub-resource-sync
Executable
+229
@@ -0,0 +1,229 @@
|
||||
#!/usr/bin/env bash
|
||||
# =============================================================================
|
||||
# Static Site Build Script
|
||||
#
|
||||
# This script performs the following tasks:
|
||||
# 1. Checks that NodeJS (>=18.0) is installed; if not, it prints instructions
|
||||
# for installing via nvm.
|
||||
# 2. Changes directory into the docs folder so that all commands run from there.
|
||||
# (Note: This ensures that the DOCS_BASE_URL value is interpreted relative
|
||||
# to the docs folder. For example, if running from the project root, the
|
||||
# effective path will be: <root>/docs/docs/latest.)
|
||||
# 3. Installs dependencies via npm.
|
||||
# 4. (Optional) Builds the API docs:
|
||||
# - If --build-api-docs is provided, then the API docs are built.
|
||||
# - If --with-r-docs is also provided, the build includes R docs;
|
||||
# otherwise, R docs are skipped.
|
||||
# 5. Converts notebooks to MDX.
|
||||
# 6. Exports the DOCS_BASE_URL environment variable (default: /docs/latest) so
|
||||
# that Docusaurus uses the proper base URL.
|
||||
# 7. Builds the static site.
|
||||
#
|
||||
# Once complete, the script instructs the user to navigate into the docs folder
|
||||
# and run:
|
||||
#
|
||||
# npm run serve -- --port <your_port_number>
|
||||
#
|
||||
# Options:
|
||||
# --build-api-docs Opt in to build the API docs (default: do not build)
|
||||
# --with-r-docs When building API docs, include R documentation
|
||||
# (default: skip R docs)
|
||||
# --docs-base-url URL Override the default DOCS_BASE_URL (default: /docs/latest)
|
||||
# -h, --help Display this help message and exit
|
||||
#
|
||||
# Example:
|
||||
# ./dev/build-docs.sh --build-api-docs --with-r-docs --docs-base-url /docs/latest
|
||||
# =============================================================================
|
||||
|
||||
# Exit immediately if a command exits with a non-zero status,
|
||||
# treat unset variables as an error, and fail on pipeline errors.
|
||||
set -euo pipefail
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Define color and style variables for styled output.
|
||||
# -----------------------------------------------------------------------------
|
||||
BOLD='\033[1m'
|
||||
RED='\033[0;31m'
|
||||
GREEN='\033[0;32m'
|
||||
YELLOW='\033[0;33m'
|
||||
BLUE='\033[0;34m'
|
||||
NC='\033[0m' # No Color
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Logging functions for consistent output styling.
|
||||
# -----------------------------------------------------------------------------
|
||||
log_info() { echo -e "${BOLD}${BLUE}[INFO]${NC} $1"; }
|
||||
log_success() { echo -e "${BOLD}${GREEN}[SUCCESS]${NC} $1"; }
|
||||
log_warning() { echo -e "${BOLD}${YELLOW}[WARNING]${NC} $1"; }
|
||||
log_error() { echo -e "${BOLD}${RED}[ERROR]${NC} $1"; }
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Default configuration values.
|
||||
# -----------------------------------------------------------------------------
|
||||
BUILD_API_DOCS=false
|
||||
WITH_R_DOCS=false
|
||||
# Default DOCS_BASE_URL is set as expected when running from within the docs folder.
|
||||
# Note: When running from the project root, since we change into docs/,
|
||||
# the effective reference becomes: <root>/docs/docs/latest.
|
||||
DOCS_BASE_URL="/docs/latest"
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Display usage information.
|
||||
# -----------------------------------------------------------------------------
|
||||
usage() {
|
||||
cat <<EOF
|
||||
Usage: $0 [options]
|
||||
|
||||
Options:
|
||||
--build-api-docs Opt in to build the API docs (default: do not build)
|
||||
--with-r-docs When building API docs, include R documentation
|
||||
(default: skip R docs)
|
||||
--docs-base-url URL Override the default DOCS_BASE_URL (default: /docs/latest)
|
||||
-h, --help Display this help and exit
|
||||
|
||||
Example:
|
||||
$0 --build-api-docs --with-r-docs --docs-base-url /docs/latest
|
||||
EOF
|
||||
}
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Parse command-line arguments manually.
|
||||
# -----------------------------------------------------------------------------
|
||||
while [[ $# -gt 0 ]]; do
|
||||
case "$1" in
|
||||
--build-api-docs)
|
||||
BUILD_API_DOCS=true
|
||||
shift
|
||||
;;
|
||||
--with-r-docs)
|
||||
WITH_R_DOCS=true
|
||||
shift
|
||||
;;
|
||||
--docs-base-url)
|
||||
if [[ -n "${2:-}" ]]; then
|
||||
DOCS_BASE_URL="$2"
|
||||
shift 2
|
||||
else
|
||||
log_error "--docs-base-url requires an argument."
|
||||
usage
|
||||
exit 1
|
||||
fi
|
||||
;;
|
||||
-h|--help)
|
||||
usage
|
||||
exit 0
|
||||
;;
|
||||
*)
|
||||
log_error "Unknown option: $1"
|
||||
usage
|
||||
exit 1
|
||||
;;
|
||||
esac
|
||||
done
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Function to compare semantic version numbers.
|
||||
# Returns 0 (true) if version $1 is greater than or equal to version $2.
|
||||
# -----------------------------------------------------------------------------
|
||||
version_ge() {
|
||||
# Usage: version_ge "18.15.0" "18.0.0"
|
||||
[ "$(printf '%s\n' "$2" "$1" | sort -V | head -n1)" = "$2" ]
|
||||
}
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Check that NodeJS is installed and meets the version requirement (>= 18.0).
|
||||
# -----------------------------------------------------------------------------
|
||||
if ! command -v node >/dev/null 2>&1; then
|
||||
log_error "NodeJS is not installed. Please install NodeJS (>= 18.0) from https://nodejs.org/ or via nvm."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
NODE_VERSION=$(node --version | sed 's/v//')
|
||||
REQUIRED_VERSION="18.0.0"
|
||||
if ! version_ge "$NODE_VERSION" "$REQUIRED_VERSION"; then
|
||||
log_error "Detected NodeJS version $NODE_VERSION. Please install NodeJS >= $REQUIRED_VERSION."
|
||||
log_info "If you have nvm installed, you can run:"
|
||||
echo -e "${BOLD}nvm install node && nvm use node${NC}"
|
||||
exit 1
|
||||
fi
|
||||
log_success "NodeJS version $NODE_VERSION is valid."
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Check that npm is installed.
|
||||
# -----------------------------------------------------------------------------
|
||||
if ! command -v npm >/dev/null 2>&1; then
|
||||
log_error "npm is not installed. Please install npm from https://nodejs.org/."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Change directory into the docs folder so that all commands run from there.
|
||||
# This ensures that DOCS_BASE_URL is interpreted correctly.
|
||||
# -----------------------------------------------------------------------------
|
||||
if [ ! -d "docs" ]; then
|
||||
log_error "The docs directory was not found. Make sure you're running this script from the project root."
|
||||
exit 1
|
||||
fi
|
||||
|
||||
log_info "Changing directory to docs/ ..."
|
||||
cd docs
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Install dependencies via npm.
|
||||
# -----------------------------------------------------------------------------
|
||||
log_info "Installing dependencies with npm..."
|
||||
npm install
|
||||
log_success "Dependencies installed."
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Optionally build the API documentation.
|
||||
# This step is opt-in via the --build-api-docs flag.
|
||||
# If building API docs, the --with-r-docs flag controls whether R docs are included.
|
||||
# -----------------------------------------------------------------------------
|
||||
if [ "$BUILD_API_DOCS" = true ]; then
|
||||
if [ "$WITH_R_DOCS" = true ]; then
|
||||
log_info "Building API docs including R documentation..."
|
||||
npm run build-api-docs
|
||||
else
|
||||
log_info "Building API docs without R documentation..."
|
||||
npm run build-api-docs:no-r
|
||||
fi
|
||||
log_success "API docs built successfully."
|
||||
else
|
||||
log_info "Skipping API docs build phase."
|
||||
fi
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Update the API module references for link functionality
|
||||
# -----------------------------------------------------------------------------
|
||||
log_info "Updating API module links..."
|
||||
npm run update-api-modules
|
||||
log_success "Updated API module links."
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Convert notebooks to MDX format.
|
||||
# -----------------------------------------------------------------------------
|
||||
log_info "Converting notebooks to MDX..."
|
||||
npm run convert-notebooks
|
||||
log_success "Notebooks converted to MDX."
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Export DOCS_BASE_URL and build the static site.
|
||||
#
|
||||
# Since we're in the docs folder, exporting DOCS_BASE_URL as "/docs/latest"
|
||||
# means that when served from the project root, the built site will be available
|
||||
# at <root>/docs/docs/latest.
|
||||
# -----------------------------------------------------------------------------
|
||||
export DOCS_BASE_URL
|
||||
log_info "DOCS_BASE_URL set to '${DOCS_BASE_URL}'."
|
||||
log_info "Building static site files with npm..."
|
||||
npm run build
|
||||
log_success "Static site built successfully."
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
# Final instructions for the user.
|
||||
# -----------------------------------------------------------------------------
|
||||
log_info "To run the site locally, please navigate to the 'docs' folder and execute:"
|
||||
echo -e "${BOLD}npm run serve -- --port <your_port_number>${NC}"
|
||||
log_info "For example: ${BOLD}npm run serve -- --port 3000${NC}"
|
||||
log_success "Static site build process completed."
|
||||
Reference in New Issue
Block a user