From 3cd15cb2e3aecc4c2e1e553d9ac7e4a7a67c46b1 Mon Sep 17 00:00:00 2001 From: Eugene Triguba Date: Sat, 11 Oct 2025 11:08:32 -0400 Subject: Add support for versioned docs --- scripts/deploy-docs.sh | 90 +++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 81 insertions(+), 9 deletions(-) (limited to 'scripts/deploy-docs.sh') diff --git a/scripts/deploy-docs.sh b/scripts/deploy-docs.sh index 7bdae3a..008d571 100755 --- a/scripts/deploy-docs.sh +++ b/scripts/deploy-docs.sh @@ -4,14 +4,19 @@ set -eou pipefail source "$(dirname "${BASH_SOURCE[0]}")/lib/log.sh" readonly SITE="bolt.eugenetriguba.com" +readonly BUILD_DIR="site" usage() { echo "Usage: $0" echo "" - echo "Build and deploy documentation to SourceHut Pages" + echo "Build and deploy versioned documentation to SourceHut Pages" + echo "" + echo "Environment variables:" + echo " VERSION - The version to deploy (default: 'latest' for main branch)" echo "" echo "Examples:" - echo " $0 # Build and deploy docs to $SITE" + echo " $0 # Deploy as 'latest'" + echo " VERSION=v1.0.0 $0 # Deploy as 'v1.0.0'" } main() { @@ -21,27 +26,94 @@ main() { fi log_header "Deploying Documentation" - build_docs + + local version="${VERSION:-latest}" + log_info "Deploying version: $version" + + fetch_existing_site + build_version "$version" + update_versions_manifest + copy_version_assets package_site - deploy_to_pages + deploy_to_pages "$version" +} + +fetch_existing_site() { + log_step "Fetching existing site" + mkdir -p "$BUILD_DIR" + + if hut pages download "$SITE" 2>/dev/null | tar -xzf - -C "$BUILD_DIR" 2>/dev/null; then + log_success "Existing site fetched" + else + log_info "No existing site found, starting fresh" + fi } -build_docs() { - log_step "Building documentation with MkDocs" - mkdocs build - log_success "Documentation built successfully" +build_version() { + local version="$1" + log_step "Building documentation for version: $version" + + mkdocs build -d "$BUILD_DIR/$version" + + # If latest, also copy to root for default view + if [[ "$version" == "latest" ]]; then + log_step "Copying latest to root" + rsync -a --delete "$BUILD_DIR/latest/" "$BUILD_DIR/" \ + --exclude="versions.json" \ + --exclude="v*" \ + --exclude="latest" + fi + + log_success "Documentation built for $version" +} + +update_versions_manifest() { + log_step "Updating versions manifest" + + # Build array of versions using jq + local versions_json="[]" + + # Add 'latest' if it exists + if [[ -d "$BUILD_DIR/latest" ]]; then + versions_json=$(echo "$versions_json" | jq '. += [{"version": "latest", "title": "Latest (Development)"}]') + fi + + # Add all tagged versions (sorted in reverse) + if compgen -G "$BUILD_DIR/v*" > /dev/null; then + for dir in $(find "$BUILD_DIR" -maxdepth 1 -type d -name "v*" | sort -Vr); do + local ver=$(basename "$dir") + versions_json=$(echo "$versions_json" | jq --arg v "$ver" '. += [{"version": $v, "title": $v}]') + done + fi + + # Create final JSON structure + jq -n --argjson versions "$versions_json" '{"versions": $versions}' > "$BUILD_DIR/versions.json" + + local version_count=$(echo "$versions_json" | jq 'length') + log_success "Versions manifest updated with $version_count version(s)" +} + +copy_version_assets() { + log_step "Copying version selector assets" + # Copy the JS file that was built into each version to the root + if [[ -f "$BUILD_DIR/latest/js/version-selector.js" ]]; then + cp "$BUILD_DIR/latest/js/version-selector.js" "$BUILD_DIR/version-selector.js" + log_success "Version selector copied to root" + fi } package_site() { log_step "Creating tarball" - tar -C site -czf site.tar.gz . + tar -C "$BUILD_DIR" -czf site.tar.gz . log_success "Site packaged as site.tar.gz" } deploy_to_pages() { + local version="$1" log_step "Deploying to SourceHut Pages: $SITE" hut pages publish -d "$SITE" site.tar.gz log_success "Documentation deployed to https://$SITE" + log_info "Version URL: https://$SITE/$version/" } main "$@" -- cgit v1.2.3