wehub-resource-sync
230 lines
9.1 KiB
Bash
Executable File
230 lines
9.1 KiB
Bash
Executable File
#!/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."
|