From 7226cfd03085a3a61105f6296f233e43a5305026 Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Wed, 11 Mar 2026 10:29:08 -0700 Subject: [PATCH 01/31] initial script and data to build the combined collection of docs individually --- .gitignore | 2 + scripts/build-docs.sh | 293 ++++++++++++++++++++++++++++++++++++++++++ scripts/sources.json | 80 ++++++++++++ 3 files changed, 375 insertions(+) create mode 100755 scripts/build-docs.sh create mode 100644 scripts/sources.json diff --git a/.gitignore b/.gitignore index dd0fa39..d8cd40f 100644 --- a/.gitignore +++ b/.gitignore @@ -3,3 +3,5 @@ .build .swiftpm Package.resolved +.build-workspace/ +.build-output/ diff --git a/scripts/build-docs.sh b/scripts/build-docs.sh new file mode 100755 index 0000000..46d726d --- /dev/null +++ b/scripts/build-docs.sh @@ -0,0 +1,293 @@ +#!/bin/bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)" +SOURCES_FILE="$SCRIPT_DIR/sources.json" + +# Defaults +OUTPUT_DIR="$ROOT_DIR/.build-output" +WORKSPACE="$ROOT_DIR/.build-workspace" +CLEAN=false +ONLY="" + +usage() { + cat < Where to export built archives (default: .build-output/) + --workspace Where to clone external repos (default: .build-workspace/) + --clean Remove workspace and re-clone everything + --only Build only a specific source by id + -h, --help Show this help message +EOF +} + +# Parse arguments +while [[ $# -gt 0 ]]; do + case "$1" in + --output-dir) + OUTPUT_DIR="$2" + shift 2 + ;; + --workspace) + WORKSPACE="$2" + shift 2 + ;; + --clean) + CLEAN=true + shift + ;; + --only) + ONLY="$2" + shift 2 + ;; + -h|--help) + usage + exit 0 + ;; + *) + echo "Unknown option: $1" + usage + exit 1 + ;; + esac +done + +# Check prerequisites +for cmd in jq swift git; do + if ! command -v "$cmd" &>/dev/null; then + echo "Error: '$cmd' is required but not found in PATH." + exit 1 + fi +done + +if [[ ! -f "$SOURCES_FILE" ]]; then + echo "Error: sources.json not found at $SOURCES_FILE" + exit 1 +fi + +if ! jq empty "$SOURCES_FILE" 2>/dev/null; then + echo "Error: sources.json is not valid JSON" + exit 1 +fi + +# Validate all source entries before doing any work +validate_sources() { + local validation_failed=false + + for i in $(seq 0 $((source_count - 1))); do + local entry entry_id entry_type entry_path entry_repo has_targets has_docc_catalog label + entry=$(jq ".[$i]" "$SOURCES_FILE") + entry_id=$(echo "$entry" | jq -r '.id // empty') + entry_type=$(echo "$entry" | jq -r '.type // empty') + entry_path=$(echo "$entry" | jq -r '.path // empty') + entry_repo=$(echo "$entry" | jq -r '.repo // empty') + has_targets=$(echo "$entry" | jq 'has("targets")') + has_docc_catalog=$(echo "$entry" | jq 'has("docc_catalog")') + + label="Entry $i" + if [[ -n "$entry_id" ]]; then + label="'$entry_id' (index $i)" + fi + + if [[ -z "$entry_id" ]]; then + echo "Validation error: $label is missing 'id'" + validation_failed=true + fi + + if [[ -z "$entry_type" ]]; then + echo "Validation error: $label is missing 'type'" + validation_failed=true + elif [[ "$entry_type" != "local" && "$entry_type" != "git" ]]; then + echo "Validation error: $label has unknown type '$entry_type' (expected 'local' or 'git')" + validation_failed=true + fi + + if [[ "$entry_type" == "local" && -z "$entry_path" ]]; then + echo "Validation error: $label is type 'local' but missing 'path'" + validation_failed=true + fi + + if [[ "$entry_type" == "git" && -z "$entry_repo" ]]; then + echo "Validation error: $label is type 'git' but missing 'repo'" + validation_failed=true + fi + + if [[ "$has_targets" == "false" && "$has_docc_catalog" == "false" ]]; then + echo "Validation error: $label must have either 'targets' or 'docc_catalog'" + validation_failed=true + fi + + if [[ "$has_targets" == "true" && "$has_docc_catalog" == "true" ]]; then + echo "Validation error: $label has both 'targets' and 'docc_catalog' (they are mutually exclusive)" + validation_failed=true + fi + done + + if [[ "$validation_failed" == true ]]; then + echo "" + echo "Fix the errors in $SOURCES_FILE before continuing." + return 1 + fi + + echo "Validated $source_count source entries." +} + +source_count=$(jq length "$SOURCES_FILE") +validate_sources + +# Fresh start if requested +if [[ "$CLEAN" == true ]]; then + echo "Removing workspace: $WORKSPACE" + rm -rf "$WORKSPACE" +fi + +mkdir -p "$OUTPUT_DIR" "$WORKSPACE" + +# Track results +declare -a SUCCEEDED=() +declare -a FAILED=() + +# Find .doccarchive files produced by swift package generate-documentation. +# They land in the .build directory tree; the exact path varies by toolchain. +find_doccarchive() { + local search_dir="$1" + local target="$2" + # Look for .doccarchive anywhere under .build + find "$search_dir/.build" -type d -name "${target}.doccarchive" 2>/dev/null | head -n 1 +} + +build_source() { + local id type path repo docc_catalog source_dir + local entry="$1" + + id=$(echo "$entry" | jq -r '.id') + type=$(echo "$entry" | jq -r '.type') + path=$(echo "$entry" | jq -r '.path // empty') + repo=$(echo "$entry" | jq -r '.repo // empty') + docc_catalog=$(echo "$entry" | jq -r '.docc_catalog // empty') + + # Read targets as a bash array (may be empty) + local targets=() + local targets_json + targets_json=$(echo "$entry" | jq -r '.targets // empty') + if [[ -n "$targets_json" ]]; then + while IFS= read -r t; do + targets+=("$t") + done < <(echo "$entry" | jq -r '.targets[]') + fi + + echo "" + echo "========================================" + echo "Building: $id" + echo "========================================" + + # Resolve source directory + if [[ "$type" == "local" ]]; then + source_dir="$ROOT_DIR/$path" + if [[ ! -d "$source_dir" ]]; then + echo "Error: local path '$source_dir' does not exist" + return 1 + fi + elif [[ "$type" == "git" ]]; then + source_dir="$WORKSPACE/$id" + if [[ -d "$source_dir/.git" ]]; then + echo "Updating existing clone..." + git -C "$source_dir" fetch --quiet origin + git -C "$source_dir" reset --quiet --hard origin/main + else + echo "Cloning $repo..." + git clone --quiet --depth 1 "$repo" "$source_dir" + fi + else + echo "Error: unknown type '$type'" + return 1 + fi + + # Build based on JSON configuration: + # targets -> swift package generate-documentation --target + # docc_catalog -> docc convert + if [[ ${#targets[@]} -gt 0 ]]; then + # Build each target via swift package + for target in "${targets[@]}"; do + echo "Building target: $target" + (cd "$source_dir" && swift package generate-documentation --target "$target") + + local archive + archive=$(find_doccarchive "$source_dir" "$target") + if [[ -z "$archive" ]]; then + echo "Error: could not find .doccarchive for target '$target'" + return 1 + fi + + local output_name="$id" + if [[ ${#targets[@]} -gt 1 ]]; then + output_name="${id}-${target}" + fi + echo "Exporting $archive -> $OUTPUT_DIR/${output_name}.doccarchive" + rm -rf "${OUTPUT_DIR:?}/${output_name}.doccarchive" + cp -R "$archive" "$OUTPUT_DIR/${output_name}.doccarchive" + done + + else + # Use docc convert directly + local catalog_path="$source_dir/$docc_catalog" + if [[ ! -d "$catalog_path" ]]; then + echo "Error: docc catalog not found at '$catalog_path'" + return 1 + fi + + local output_path="$OUTPUT_DIR/${id}.doccarchive" + echo "Converting catalog with docc convert..." + rm -rf "$output_path" + + # Find the docc tool — prefer xcrun on macOS, fall back to PATH + local docc_cmd + if command -v xcrun &>/dev/null && xcrun --find docc &>/dev/null 2>&1; then + docc_cmd="xcrun docc" + elif command -v docc &>/dev/null; then + docc_cmd="docc" + else + echo "Error: 'docc' tool not found (tried xcrun and PATH)" + return 1 + fi + + $docc_cmd convert "$catalog_path" --output-path "$output_path" + fi + + echo "Done: $id" +} + +# Read sources and iterate +for i in $(seq 0 $((source_count - 1))); do + entry=$(jq ".[$i]" "$SOURCES_FILE") + entry_id=$(echo "$entry" | jq -r '.id') + + # Filter if --only is set + if [[ -n "$ONLY" ]] && [[ "$entry_id" != "$ONLY" ]]; then + continue + fi + + if build_source "$entry"; then + SUCCEEDED+=("$entry_id") + else + FAILED+=("$entry_id") + fi +done + +# Summary +echo "" +echo "========================================" +echo "Build Summary" +echo "========================================" +echo "Succeeded (${#SUCCEEDED[@]}): ${SUCCEEDED[*]:-none}" +echo "Failed (${#FAILED[@]}): ${FAILED[*]:-none}" +echo "Output: $OUTPUT_DIR" + +if [[ ${#FAILED[@]} -gt 0 ]]; then + exit 1 +fi diff --git a/scripts/sources.json b/scripts/sources.json new file mode 100644 index 0000000..71f8298 --- /dev/null +++ b/scripts/sources.json @@ -0,0 +1,80 @@ +[ + { + "id": "api-guidelines", + "type": "local", + "path": "api-guidelines", + "targets": ["APIGuidelines"] + }, + { + "id": "language-guides", + "type": "local", + "path": "language-guides", + "targets": ["LanguageGuides"] + }, + { + "id": "server-guides", + "type": "local", + "path": "server-guides", + "targets": ["ServerGuides"] + }, + { + "id": "ecosystem-tools", + "type": "local", + "path": "ecosystem-tools", + "targets": ["EcosystemTools"] + }, + { + "id": "swift-book", + "type": "git", + "repo": "https://github.com/swiftlang/swift-book.git", + "docc_catalog": "TSPL.docc" + }, + { + "id": "swift-migration-guide", + "type": "git", + "repo": "https://github.com/swiftlang/swift-migration-guide.git", + "docc_catalog": "Guide.docc" + }, + { + "id": "docc-documentation", + "type": "git", + "repo": "https://github.com/swiftlang/swift-docc.git", + "docc_catalog": "Sources/docc/DocCDocumentation.docc" + }, + { + "id": "swiftpm", + "type": "git", + "repo": "https://github.com/swiftlang/swift-package-manager.git", + "targets": ["PackageManagerDocs", "PackageDescription", "PackagePlugin"] + }, + { + "id": "swiftly", + "type": "git", + "repo": "https://github.com/swiftlang/swiftly.git", + "targets": ["SwiftlyDocs"] + }, + { + "id": "vscode-swift", + "type": "git", + "repo": "https://github.com/swiftlang/vscode-swift.git", + "docc_catalog": "userdocs/userdocs.docc" + }, + { + "id": "compiler-diagnostics", + "type": "git", + "repo": "https://github.com/swiftlang/swift.git", + "docc_catalog": "userdocs/diagnostics" + }, + { + "id": "embedded-swift", + "type": "git", + "repo": "https://github.com/swiftlang/swift-embedded-examples.git", + "targets": ["EmbeddedSwift"] + }, + { + "id": "swift-server-todos-tutorial", + "type": "git", + "repo": "https://github.com/swiftlang/swift-server-todos-tutorial.git", + "docc_catalog": "SwiftServerTodos.docc" + } +] From 4f4960665f966afe40103ba1cff5295cd68a80da Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Wed, 11 Mar 2026 10:45:37 -0700 Subject: [PATCH 02/31] updates to combine, use header/footer --- scripts/build-docs.sh | 191 +++++++++++++++++++++++++++++++++++++++--- scripts/sources.json | 33 +++++--- 2 files changed, 201 insertions(+), 23 deletions(-) diff --git a/scripts/build-docs.sh b/scripts/build-docs.sh index 46d726d..b439695 100755 --- a/scripts/build-docs.sh +++ b/scripts/build-docs.sh @@ -5,6 +5,20 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)" SOURCES_FILE="$SCRIPT_DIR/sources.json" +# Ensure consistent, pretty-printed DocC JSON output +export DOCC_JSON_PRETTYPRINT=YES + +# Common DocC build flags applied to all documentation builds +DOCC_BUILD_FLAGS=( + --experimental-enable-custom-templates + --enable-mentioned-in + --enable-experimental-external-link-support +) + +# Common template files to copy into each .docc catalog before building +COMMON_DIR="$ROOT_DIR/common" +TEMPLATE_FILES=(header.html footer.html) + # Defaults OUTPUT_DIR="$ROOT_DIR/.build-output" WORKSPACE="$ROOT_DIR/.build-workspace" @@ -75,6 +89,14 @@ if ! jq empty "$SOURCES_FILE" 2>/dev/null; then exit 1 fi +# Validate common template files exist +for tmpl in "${TEMPLATE_FILES[@]}"; do + if [[ ! -f "$COMMON_DIR/$tmpl" ]]; then + echo "Error: common template '$tmpl' not found at $COMMON_DIR/$tmpl" + exit 1 + fi +done + # Validate all source entries before doing any work validate_sources() { local validation_failed=false @@ -151,6 +173,21 @@ mkdir -p "$OUTPUT_DIR" "$WORKSPACE" # Track results declare -a SUCCEEDED=() declare -a FAILED=() +declare -a COMBINED_ARCHIVES=() +declare -a COMBINED_EXPECTED_IDS=() + +# Find the docc tool — prefer xcrun on macOS, fall back to PATH. +# Resolved once and reused throughout. +resolve_docc_cmd() { + if command -v xcrun &>/dev/null && xcrun --find docc &>/dev/null 2>&1; then + echo "xcrun docc" + elif command -v docc &>/dev/null; then + echo "docc" + else + echo "" + fi +} +DOCC_CMD=$(resolve_docc_cmd) # Find .doccarchive files produced by swift package generate-documentation. # They land in the .build directory tree; the exact path varies by toolchain. @@ -161,6 +198,40 @@ find_doccarchive() { find "$search_dir/.build" -type d -name "${target}.doccarchive" 2>/dev/null | head -n 1 } +# Discover the .docc catalog directory for a Swift package target using +# `swift package describe`. Returns the path relative to the package root. +find_docc_catalog_for_target() { + local source_dir="$1" + local target="$2" + + local target_path + target_path=$(cd "$source_dir" && swift package describe --type json 2>/dev/null \ + | jq -r --arg t "$target" '.targets[] | select(.name == $t) | .path') + + if [[ -z "$target_path" ]]; then + echo "" + return + fi + + # Look for a .docc directory inside the target's source path + find "$source_dir/$target_path" -maxdepth 1 -name "*.docc" -type d 2>/dev/null | head -n 1 +} + +# Copy common template files (header.html, footer.html) into a .docc catalog. +# Warns if the catalog already contains a file that will be overwritten. +install_templates() { + local catalog_dir="$1" + local source_id="$2" + + for tmpl in "${TEMPLATE_FILES[@]}"; do + if [[ -f "$catalog_dir/$tmpl" ]]; then + echo " WARNING: overwriting existing $tmpl in $source_id catalog" + fi + cp "$COMMON_DIR/$tmpl" "$catalog_dir/$tmpl" + echo " Installed $tmpl -> $catalog_dir/" + done +} + build_source() { local id type path repo docc_catalog source_dir local entry="$1" @@ -170,6 +241,8 @@ build_source() { path=$(echo "$entry" | jq -r '.path // empty') repo=$(echo "$entry" | jq -r '.repo // empty') docc_catalog=$(echo "$entry" | jq -r '.docc_catalog // empty') + local is_combined + is_combined=$(echo "$entry" | jq -r '.combined // false') # Read targets as a bash array (may be empty) local targets=() @@ -212,10 +285,23 @@ build_source() { # targets -> swift package generate-documentation --target # docc_catalog -> docc convert if [[ ${#targets[@]} -gt 0 ]]; then + # Install templates into each target's .docc catalog + for target in "${targets[@]}"; do + local catalog_dir + catalog_dir=$(find_docc_catalog_for_target "$source_dir" "$target") + if [[ -n "$catalog_dir" ]]; then + install_templates "$catalog_dir" "$id/$target" + else + echo " Note: could not locate .docc catalog for target '$target', skipping template install" + fi + done + # Build each target via swift package for target in "${targets[@]}"; do echo "Building target: $target" - (cd "$source_dir" && swift package generate-documentation --target "$target") + (cd "$source_dir" && swift package generate-documentation \ + --target "$target" \ + "${DOCC_BUILD_FLAGS[@]}") local archive archive=$(find_doccarchive "$source_dir" "$target") @@ -231,6 +317,10 @@ build_source() { echo "Exporting $archive -> $OUTPUT_DIR/${output_name}.doccarchive" rm -rf "${OUTPUT_DIR:?}/${output_name}.doccarchive" cp -R "$archive" "$OUTPUT_DIR/${output_name}.doccarchive" + + if [[ "$is_combined" == "true" ]]; then + COMBINED_ARCHIVES+=("$OUTPUT_DIR/${output_name}.doccarchive") + fi done else @@ -241,22 +331,24 @@ build_source() { return 1 fi + if [[ -z "$DOCC_CMD" ]]; then + echo "Error: 'docc' tool not found (tried xcrun and PATH)" + return 1 + fi + + # Install templates into the catalog + install_templates "$catalog_path" "$id" + local output_path="$OUTPUT_DIR/${id}.doccarchive" echo "Converting catalog with docc convert..." rm -rf "$output_path" - # Find the docc tool — prefer xcrun on macOS, fall back to PATH - local docc_cmd - if command -v xcrun &>/dev/null && xcrun --find docc &>/dev/null 2>&1; then - docc_cmd="xcrun docc" - elif command -v docc &>/dev/null; then - docc_cmd="docc" - else - echo "Error: 'docc' tool not found (tried xcrun and PATH)" - return 1 - fi + $DOCC_CMD convert "$catalog_path" --output-path "$output_path" \ + "${DOCC_BUILD_FLAGS[@]}" - $docc_cmd convert "$catalog_path" --output-path "$output_path" + if [[ "$is_combined" == "true" ]]; then + COMBINED_ARCHIVES+=("$output_path") + fi fi echo "Done: $id" @@ -272,6 +364,12 @@ for i in $(seq 0 $((source_count - 1))); do continue fi + is_combined=$(echo "$entry" | jq -r '.combined // false') + + if [[ "$is_combined" == "true" ]]; then + COMBINED_EXPECTED_IDS+=("$entry_id") + fi + if build_source "$entry"; then SUCCEEDED+=("$entry_id") else @@ -279,6 +377,75 @@ for i in $(seq 0 $((source_count - 1))); do fi done +# Merge combined archives — only if all combined sources built successfully +if [[ ${#COMBINED_EXPECTED_IDS[@]} -gt 0 && -z "$ONLY" ]]; then + echo "" + echo "========================================" + echo "Merging combined documentation archive" + echo "========================================" + + # Check that no combined source appears in the FAILED list + combined_failures=() + for cid in "${COMBINED_EXPECTED_IDS[@]}"; do + for fid in ${FAILED[@]+"${FAILED[@]}"}; do + if [[ "$cid" == "$fid" ]]; then + combined_failures+=("$cid") + fi + done + done + + if [[ ${#combined_failures[@]} -gt 0 ]]; then + echo "Error: cannot merge — the following combined sources failed to build:" + for cf in "${combined_failures[@]}"; do + echo " - $cf" + done + echo "Skipping merge step." + FAILED+=("combined-merge") + + elif [[ ${#COMBINED_ARCHIVES[@]} -eq 0 ]]; then + echo "Error: no combined archives were produced despite all sources succeeding" + FAILED+=("combined-merge") + + elif [[ -z "$DOCC_CMD" ]]; then + echo "Error: 'docc' tool not found, cannot merge archives" + FAILED+=("combined-merge") + + else + # Verify every expected archive exists on disk + missing_archives=() + for a in "${COMBINED_ARCHIVES[@]}"; do + if [[ ! -d "$a" ]]; then + missing_archives+=("$a") + fi + done + + if [[ ${#missing_archives[@]} -gt 0 ]]; then + echo "Error: the following expected archives are missing:" + for ma in "${missing_archives[@]}"; do + echo " - $ma" + done + FAILED+=("combined-merge") + else + COMBINED_OUTPUT="$OUTPUT_DIR/Combined.doccarchive" + rm -rf "$COMBINED_OUTPUT" + + echo "Merging ${#COMBINED_ARCHIVES[@]} archives..." + for a in "${COMBINED_ARCHIVES[@]}"; do + echo " - $(basename "$a")" + done + + if $DOCC_CMD merge "${COMBINED_ARCHIVES[@]}" \ + --output-path "$COMBINED_OUTPUT"; then + echo "Combined archive: $COMBINED_OUTPUT" + SUCCEEDED+=("combined-merge") + else + echo "Error: docc merge failed" + FAILED+=("combined-merge") + fi + fi + fi +fi + # Summary echo "" echo "========================================" diff --git a/scripts/sources.json b/scripts/sources.json index 71f8298..ce7b8f6 100644 --- a/scripts/sources.json +++ b/scripts/sources.json @@ -3,49 +3,57 @@ "id": "api-guidelines", "type": "local", "path": "api-guidelines", - "targets": ["APIGuidelines"] + "targets": ["APIGuidelines"], + "combined": true }, { "id": "language-guides", "type": "local", "path": "language-guides", - "targets": ["LanguageGuides"] + "targets": ["LanguageGuides"], + "combined": true }, { "id": "server-guides", "type": "local", "path": "server-guides", - "targets": ["ServerGuides"] + "targets": ["ServerGuides"], + "combined": true }, { "id": "ecosystem-tools", "type": "local", "path": "ecosystem-tools", - "targets": ["EcosystemTools"] + "targets": ["EcosystemTools"], + "combined": true }, { "id": "swift-book", "type": "git", "repo": "https://github.com/swiftlang/swift-book.git", - "docc_catalog": "TSPL.docc" + "docc_catalog": "TSPL.docc", + "combined": true }, { "id": "swift-migration-guide", "type": "git", "repo": "https://github.com/swiftlang/swift-migration-guide.git", - "docc_catalog": "Guide.docc" + "docc_catalog": "Guide.docc", + "combined": true }, { "id": "docc-documentation", "type": "git", "repo": "https://github.com/swiftlang/swift-docc.git", - "docc_catalog": "Sources/docc/DocCDocumentation.docc" + "docc_catalog": "Sources/docc/DocCDocumentation.docc", + "combined": true }, { "id": "swiftpm", "type": "git", "repo": "https://github.com/swiftlang/swift-package-manager.git", - "targets": ["PackageManagerDocs", "PackageDescription", "PackagePlugin"] + "targets": ["PackageManagerDocs", "PackageDescription", "PackagePlugin"], + "combined": true }, { "id": "swiftly", @@ -63,18 +71,21 @@ "id": "compiler-diagnostics", "type": "git", "repo": "https://github.com/swiftlang/swift.git", - "docc_catalog": "userdocs/diagnostics" + "docc_catalog": "userdocs/diagnostics", + "combined": true }, { "id": "embedded-swift", "type": "git", "repo": "https://github.com/swiftlang/swift-embedded-examples.git", - "targets": ["EmbeddedSwift"] + "targets": ["EmbeddedSwift"], + "combined": true }, { "id": "swift-server-todos-tutorial", "type": "git", "repo": "https://github.com/swiftlang/swift-server-todos-tutorial.git", - "docc_catalog": "SwiftServerTodos.docc" + "docc_catalog": "SwiftServerTodos.docc", + "combined": true } ] From f5b6b678c0ca360836165da1fe8e0e9f6b546bc5 Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Wed, 11 Mar 2026 10:59:35 -0700 Subject: [PATCH 03/31] fix for special case of diagnostics directory --- scripts/build-docs.sh | 16 ++++++++++++++-- scripts/sources.json | 3 ++- 2 files changed, 16 insertions(+), 3 deletions(-) diff --git a/scripts/build-docs.sh b/scripts/build-docs.sh index b439695..661f756 100755 --- a/scripts/build-docs.sh +++ b/scripts/build-docs.sh @@ -244,6 +244,16 @@ build_source() { local is_combined is_combined=$(echo "$entry" | jq -r '.combined // false') + # Read per-source extra flags as a bash array (may be empty) + local extra_flags=() + local extra_flags_json + extra_flags_json=$(echo "$entry" | jq -r '.extra_flags // empty') + if [[ -n "$extra_flags_json" ]]; then + while IFS= read -r f; do + extra_flags+=("$f") + done < <(echo "$entry" | jq -r '.extra_flags[]') + fi + # Read targets as a bash array (may be empty) local targets=() local targets_json @@ -301,7 +311,8 @@ build_source() { echo "Building target: $target" (cd "$source_dir" && swift package generate-documentation \ --target "$target" \ - "${DOCC_BUILD_FLAGS[@]}") + "${DOCC_BUILD_FLAGS[@]}" \ + ${extra_flags[@]+"${extra_flags[@]}"}) local archive archive=$(find_doccarchive "$source_dir" "$target") @@ -344,7 +355,8 @@ build_source() { rm -rf "$output_path" $DOCC_CMD convert "$catalog_path" --output-path "$output_path" \ - "${DOCC_BUILD_FLAGS[@]}" + "${DOCC_BUILD_FLAGS[@]}" \ + ${extra_flags[@]+"${extra_flags[@]}"} if [[ "$is_combined" == "true" ]]; then COMBINED_ARCHIVES+=("$output_path") diff --git a/scripts/sources.json b/scripts/sources.json index ce7b8f6..913b595 100644 --- a/scripts/sources.json +++ b/scripts/sources.json @@ -72,7 +72,8 @@ "type": "git", "repo": "https://github.com/swiftlang/swift.git", "docc_catalog": "userdocs/diagnostics", - "combined": true + "combined": true, + "extra_flags": ["--allow-arbitrary-catalog-directories"] }, { "id": "embedded-swift", From d704b4b80dc661f9871c0dc8a92f66d04ca71727 Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Wed, 11 Mar 2026 11:06:20 -0700 Subject: [PATCH 04/31] script updates for embedded and cleaner names --- .gitignore | 1 + scripts/build-docs.sh | 4 ++-- scripts/sources.json | 2 +- 3 files changed, 4 insertions(+), 3 deletions(-) diff --git a/.gitignore b/.gitignore index d8cd40f..cdac006 100644 --- a/.gitignore +++ b/.gitignore @@ -4,4 +4,5 @@ .swiftpm Package.resolved .build-workspace/ +.workspace/ .build-output/ diff --git a/scripts/build-docs.sh b/scripts/build-docs.sh index 661f756..47ecb74 100755 --- a/scripts/build-docs.sh +++ b/scripts/build-docs.sh @@ -21,7 +21,7 @@ TEMPLATE_FILES=(header.html footer.html) # Defaults OUTPUT_DIR="$ROOT_DIR/.build-output" -WORKSPACE="$ROOT_DIR/.build-workspace" +WORKSPACE="$ROOT_DIR/.workspace" CLEAN=false ONLY="" @@ -33,7 +33,7 @@ Build and export DocC documentation archives from multiple sources. Options: --output-dir Where to export built archives (default: .build-output/) - --workspace Where to clone external repos (default: .build-workspace/) + --workspace Where to clone external repos (default: .workspace/) --clean Remove workspace and re-clone everything --only Build only a specific source by id -h, --help Show this help message diff --git a/scripts/sources.json b/scripts/sources.json index 913b595..71fcbb3 100644 --- a/scripts/sources.json +++ b/scripts/sources.json @@ -79,7 +79,7 @@ "id": "embedded-swift", "type": "git", "repo": "https://github.com/swiftlang/swift-embedded-examples.git", - "targets": ["EmbeddedSwift"], + "docc_catalog": "Sources/EmbeddedSwift/Documentation.docc", "combined": true }, { From 85e7c39f3858bd7c0e3ae29135224b4f478c93a6 Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Wed, 11 Mar 2026 11:11:13 -0700 Subject: [PATCH 05/31] ignore the header and footer inclusions from the build process --- .gitignore | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.gitignore b/.gitignore index cdac006..a206102 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,5 @@ Package.resolved .build-workspace/ .workspace/ .build-output/ +**/*.docc/header.html +**/*.docc/footer.html From 560aa03ace9e64117616197b1b16e1a86c2b7adc Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Wed, 11 Mar 2026 16:48:05 -0700 Subject: [PATCH 06/31] adding spaces into names for targets --- api-guidelines/Package.swift | 4 ++-- ecosystem-tools/Package.swift | 4 ++-- language-guides/Package.swift | 4 ++-- server-guides/Package.swift | 4 ++-- 4 files changed, 8 insertions(+), 8 deletions(-) diff --git a/api-guidelines/Package.swift b/api-guidelines/Package.swift index b492431..7f0a12c 100644 --- a/api-guidelines/Package.swift +++ b/api-guidelines/Package.swift @@ -3,13 +3,13 @@ import PackageDescription let package = Package( - name: "APIGuidelines", + name: "API Guidelines", dependencies: [ .package(url: "https://github.com/swiftlang/swift-docc-plugin", from: "1.1.0") ], targets: [ .target( - name: "APIGuidelines", + name: "API Guidelines", path: "Sources" ) ] diff --git a/ecosystem-tools/Package.swift b/ecosystem-tools/Package.swift index 4616908..e47d586 100644 --- a/ecosystem-tools/Package.swift +++ b/ecosystem-tools/Package.swift @@ -3,13 +3,13 @@ import PackageDescription let package = Package( - name: "EcosystemTools", + name: "Editors and Tools", dependencies: [ .package(url: "https://github.com/swiftlang/swift-docc-plugin", from: "1.1.0") ], targets: [ .target( - name: "EcosystemTools", + name: "Editors and Tools", path: "Sources" ) ] diff --git a/language-guides/Package.swift b/language-guides/Package.swift index 1bc2445..0e01385 100644 --- a/language-guides/Package.swift +++ b/language-guides/Package.swift @@ -3,13 +3,13 @@ import PackageDescription let package = Package( - name: "LanguageGuides", + name: "Language Guides", dependencies: [ .package(url: "https://github.com/swiftlang/swift-docc-plugin", from: "1.1.0") ], targets: [ .target( - name: "LanguageGuides", + name: "Language Guides", path: "Sources" ) ] diff --git a/server-guides/Package.swift b/server-guides/Package.swift index e980467..33881bf 100644 --- a/server-guides/Package.swift +++ b/server-guides/Package.swift @@ -3,13 +3,13 @@ import PackageDescription let package = Package( - name: "ServerGuides", + name: "Server Guides", dependencies: [ .package(url: "https://github.com/swiftlang/swift-docc-plugin", from: "1.1.0") ], targets: [ .target( - name: "ServerGuides", + name: "Server Guides", path: "Sources" ) ] From 02332f8964eb286cfb21fada376296a448cd9400 Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Wed, 11 Mar 2026 17:04:34 -0700 Subject: [PATCH 07/31] nicer collection names --- .../Sources/APIGuidelines.docc/Documentation.md | 2 +- .../Sources/EcosystemTools.docc/Documentation.md | 2 +- scripts/sources.json | 8 ++++---- server-guides/Sources/ServerGuides.docc/Documentation.md | 2 +- 4 files changed, 7 insertions(+), 7 deletions(-) diff --git a/api-guidelines/Sources/APIGuidelines.docc/Documentation.md b/api-guidelines/Sources/APIGuidelines.docc/Documentation.md index 087098b..b41ae97 100644 --- a/api-guidelines/Sources/APIGuidelines.docc/Documentation.md +++ b/api-guidelines/Sources/APIGuidelines.docc/Documentation.md @@ -1 +1 @@ -# ``APIGuidelines`` +# ``API_Guidelines`` diff --git a/ecosystem-tools/Sources/EcosystemTools.docc/Documentation.md b/ecosystem-tools/Sources/EcosystemTools.docc/Documentation.md index eadc7bf..9369f63 100644 --- a/ecosystem-tools/Sources/EcosystemTools.docc/Documentation.md +++ b/ecosystem-tools/Sources/EcosystemTools.docc/Documentation.md @@ -1,2 +1,2 @@ -# ``EcosystemTools`` +# ``Editors_and_Tools`` diff --git a/scripts/sources.json b/scripts/sources.json index 71fcbb3..d74159f 100644 --- a/scripts/sources.json +++ b/scripts/sources.json @@ -3,28 +3,28 @@ "id": "api-guidelines", "type": "local", "path": "api-guidelines", - "targets": ["APIGuidelines"], + "targets": ["API Guidelines"], "combined": true }, { "id": "language-guides", "type": "local", "path": "language-guides", - "targets": ["LanguageGuides"], + "targets": ["Language Guides"], "combined": true }, { "id": "server-guides", "type": "local", "path": "server-guides", - "targets": ["ServerGuides"], + "targets": ["Server Guides"], "combined": true }, { "id": "ecosystem-tools", "type": "local", "path": "ecosystem-tools", - "targets": ["EcosystemTools"], + "targets": ["Editors and Tools"], "combined": true }, { diff --git a/server-guides/Sources/ServerGuides.docc/Documentation.md b/server-guides/Sources/ServerGuides.docc/Documentation.md index 5d22428..90b1158 100644 --- a/server-guides/Sources/ServerGuides.docc/Documentation.md +++ b/server-guides/Sources/ServerGuides.docc/Documentation.md @@ -1,2 +1,2 @@ -# ``ServerGuides`` +# ``Server_Guides`` From 9e217c89e7547df052e90a6e93485508c6608c0b Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Wed, 11 Mar 2026 17:12:27 -0700 Subject: [PATCH 08/31] missed one --- language-guides/Sources/LanguageGuides.docc/Documentation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/language-guides/Sources/LanguageGuides.docc/Documentation.md b/language-guides/Sources/LanguageGuides.docc/Documentation.md index 44d65c5..765d63e 100644 --- a/language-guides/Sources/LanguageGuides.docc/Documentation.md +++ b/language-guides/Sources/LanguageGuides.docc/Documentation.md @@ -1,2 +1,2 @@ -# ``LanguageGuides`` +# ``Language_Guides`` From e633f1e240d5eb8728908bcb7c71281682bf6514 Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Thu, 12 Mar 2026 09:14:16 -0700 Subject: [PATCH 09/31] adding WASM docc collection that's hosted at https://docs.swift.org/wasm/documentation/wasmguide/ --- scripts/sources.json | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/scripts/sources.json b/scripts/sources.json index d74159f..61c1ac4 100644 --- a/scripts/sources.json +++ b/scripts/sources.json @@ -88,5 +88,12 @@ "repo": "https://github.com/swiftlang/swift-server-todos-tutorial.git", "docc_catalog": "SwiftServerTodos.docc", "combined": true + }, + { + "id": "swift-wasm", + "type": "git", + "repo": "https://github.com/swiftlang/swift-for-wasm-examples.git", + "targets": ["WasmGuide"], + "combined": true } ] From bdaa2835af65fe9e90d90d8418756cda7857bfb3 Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Thu, 12 Mar 2026 11:03:41 -0700 Subject: [PATCH 10/31] naming trials, ordering check --- api-guidelines/Package.swift | 4 ++-- .../Sources/APIGuidelines.docc/Documentation.md | 6 +++++- scripts/sources.json | 16 ++++++++-------- 3 files changed, 15 insertions(+), 11 deletions(-) diff --git a/api-guidelines/Package.swift b/api-guidelines/Package.swift index 7f0a12c..b492431 100644 --- a/api-guidelines/Package.swift +++ b/api-guidelines/Package.swift @@ -3,13 +3,13 @@ import PackageDescription let package = Package( - name: "API Guidelines", + name: "APIGuidelines", dependencies: [ .package(url: "https://github.com/swiftlang/swift-docc-plugin", from: "1.1.0") ], targets: [ .target( - name: "API Guidelines", + name: "APIGuidelines", path: "Sources" ) ] diff --git a/api-guidelines/Sources/APIGuidelines.docc/Documentation.md b/api-guidelines/Sources/APIGuidelines.docc/Documentation.md index b41ae97..0461ddc 100644 --- a/api-guidelines/Sources/APIGuidelines.docc/Documentation.md +++ b/api-guidelines/Sources/APIGuidelines.docc/Documentation.md @@ -1 +1,5 @@ -# ``API_Guidelines`` +# ``APIGuidelines`` + +@Metadata { + @DisplayName("API Guidelines") +} \ No newline at end of file diff --git a/scripts/sources.json b/scripts/sources.json index 61c1ac4..b257bbe 100644 --- a/scripts/sources.json +++ b/scripts/sources.json @@ -1,9 +1,16 @@ [ + { + "id": "swift-book", + "type": "git", + "repo": "https://github.com/swiftlang/swift-book.git", + "docc_catalog": "TSPL.docc", + "combined": true + }, { "id": "api-guidelines", "type": "local", "path": "api-guidelines", - "targets": ["API Guidelines"], + "targets": ["APIGuidelines"], "combined": true }, { @@ -27,13 +34,6 @@ "targets": ["Editors and Tools"], "combined": true }, - { - "id": "swift-book", - "type": "git", - "repo": "https://github.com/swiftlang/swift-book.git", - "docc_catalog": "TSPL.docc", - "combined": true - }, { "id": "swift-migration-guide", "type": "git", From de6c6891052d604334c7eea9460a63885438c580 Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Thu, 12 Mar 2026 11:45:30 -0700 Subject: [PATCH 11/31] noting ordering impact in script --- scripts/build-docs.sh | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/scripts/build-docs.sh b/scripts/build-docs.sh index 47ecb74..3d7650c 100755 --- a/scripts/build-docs.sh +++ b/scripts/build-docs.sh @@ -5,6 +5,10 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)" SOURCES_FILE="$SCRIPT_DIR/sources.json" +# NOTE: The order of the archives in sources.json matters for merging into a combined archive, +# as they're listed in the order they are merged, which is driven (in this script) +# by the ordering in the JSON. + # Ensure consistent, pretty-printed DocC JSON output export DOCC_JSON_PRETTYPRINT=YES From f96f8843a429cbc4b03a86fa2d7323137abc5f42 Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Thu, 12 Mar 2026 11:57:42 -0700 Subject: [PATCH 12/31] naming tweaks and resetting package names back to make it easier to reference in DocC --- ecosystem-tools/Package.swift | 4 ++-- .../Sources/EcosystemTools.docc/Documentation.md | 5 ++++- language-guides/Package.swift | 4 ++-- .../Sources/LanguageGuides.docc/Documentation.md | 5 ++++- scripts/sources.json | 6 +++--- server-guides/Package.swift | 4 ++-- server-guides/Sources/ServerGuides.docc/Documentation.md | 5 ++++- 7 files changed, 21 insertions(+), 12 deletions(-) diff --git a/ecosystem-tools/Package.swift b/ecosystem-tools/Package.swift index e47d586..4616908 100644 --- a/ecosystem-tools/Package.swift +++ b/ecosystem-tools/Package.swift @@ -3,13 +3,13 @@ import PackageDescription let package = Package( - name: "Editors and Tools", + name: "EcosystemTools", dependencies: [ .package(url: "https://github.com/swiftlang/swift-docc-plugin", from: "1.1.0") ], targets: [ .target( - name: "Editors and Tools", + name: "EcosystemTools", path: "Sources" ) ] diff --git a/ecosystem-tools/Sources/EcosystemTools.docc/Documentation.md b/ecosystem-tools/Sources/EcosystemTools.docc/Documentation.md index 9369f63..e92873a 100644 --- a/ecosystem-tools/Sources/EcosystemTools.docc/Documentation.md +++ b/ecosystem-tools/Sources/EcosystemTools.docc/Documentation.md @@ -1,2 +1,5 @@ -# ``Editors_and_Tools`` +# ``EcosystemTools`` +@Metadata { + @DisplayName("Tools and Editors") +} \ No newline at end of file diff --git a/language-guides/Package.swift b/language-guides/Package.swift index 0e01385..1bc2445 100644 --- a/language-guides/Package.swift +++ b/language-guides/Package.swift @@ -3,13 +3,13 @@ import PackageDescription let package = Package( - name: "Language Guides", + name: "LanguageGuides", dependencies: [ .package(url: "https://github.com/swiftlang/swift-docc-plugin", from: "1.1.0") ], targets: [ .target( - name: "Language Guides", + name: "LanguageGuides", path: "Sources" ) ] diff --git a/language-guides/Sources/LanguageGuides.docc/Documentation.md b/language-guides/Sources/LanguageGuides.docc/Documentation.md index 765d63e..5d7f9b0 100644 --- a/language-guides/Sources/LanguageGuides.docc/Documentation.md +++ b/language-guides/Sources/LanguageGuides.docc/Documentation.md @@ -1,2 +1,5 @@ -# ``Language_Guides`` +# ``LanguageGuides`` +@Metadata { + @DisplayName("Language Guides") +} \ No newline at end of file diff --git a/scripts/sources.json b/scripts/sources.json index b257bbe..7d83f73 100644 --- a/scripts/sources.json +++ b/scripts/sources.json @@ -17,21 +17,21 @@ "id": "language-guides", "type": "local", "path": "language-guides", - "targets": ["Language Guides"], + "targets": ["LanguageGuides"], "combined": true }, { "id": "server-guides", "type": "local", "path": "server-guides", - "targets": ["Server Guides"], + "targets": ["ServerGuides"], "combined": true }, { "id": "ecosystem-tools", "type": "local", "path": "ecosystem-tools", - "targets": ["Editors and Tools"], + "targets": ["EcosystemTools"], "combined": true }, { diff --git a/server-guides/Package.swift b/server-guides/Package.swift index 33881bf..e980467 100644 --- a/server-guides/Package.swift +++ b/server-guides/Package.swift @@ -3,13 +3,13 @@ import PackageDescription let package = Package( - name: "Server Guides", + name: "ServerGuides", dependencies: [ .package(url: "https://github.com/swiftlang/swift-docc-plugin", from: "1.1.0") ], targets: [ .target( - name: "Server Guides", + name: "ServerGuides", path: "Sources" ) ] diff --git a/server-guides/Sources/ServerGuides.docc/Documentation.md b/server-guides/Sources/ServerGuides.docc/Documentation.md index 90b1158..2cab231 100644 --- a/server-guides/Sources/ServerGuides.docc/Documentation.md +++ b/server-guides/Sources/ServerGuides.docc/Documentation.md @@ -1,2 +1,5 @@ -# ``Server_Guides`` +# ``ServerGuides`` +@Metadata { + @DisplayName("Server Guides") +} \ No newline at end of file From f8139fe6126b1b9b38993d4f606451907517596a Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Thu, 12 Mar 2026 13:19:13 -0700 Subject: [PATCH 13/31] branching support, injecting docc-plugin --- scripts/build-docs.sh | 42 ++++++++++++++++++---- scripts/sources.json | 82 +++++++++++++++++++++++++------------------ 2 files changed, 82 insertions(+), 42 deletions(-) diff --git a/scripts/build-docs.sh b/scripts/build-docs.sh index 3d7650c..5161475 100755 --- a/scripts/build-docs.sh +++ b/scripts/build-docs.sh @@ -106,12 +106,13 @@ validate_sources() { local validation_failed=false for i in $(seq 0 $((source_count - 1))); do - local entry entry_id entry_type entry_path entry_repo has_targets has_docc_catalog label + local entry entry_id entry_type entry_path entry_repo entry_branch has_targets has_docc_catalog label entry=$(jq ".[$i]" "$SOURCES_FILE") entry_id=$(echo "$entry" | jq -r '.id // empty') entry_type=$(echo "$entry" | jq -r '.type // empty') entry_path=$(echo "$entry" | jq -r '.path // empty') entry_repo=$(echo "$entry" | jq -r '.repo // empty') + entry_branch=$(echo "$entry" | jq -r '.branch // empty') has_targets=$(echo "$entry" | jq 'has("targets")') has_docc_catalog=$(echo "$entry" | jq 'has("docc_catalog")') @@ -152,6 +153,18 @@ validate_sources() { echo "Validation error: $label has both 'targets' and 'docc_catalog' (they are mutually exclusive)" validation_failed=true fi + + if [[ -n "$entry_branch" && "$entry_type" != "git" ]]; then + echo "Validation error: $label has 'branch' but is not type 'git'" + validation_failed=true + fi + + local add_docc_plugin + add_docc_plugin=$(echo "$entry" | jq -r '.add_docc_plugin // false') + if [[ "$add_docc_plugin" == "true" && "$entry_type" != "git" ]]; then + echo "Validation error: $label has 'add_docc_plugin' but is not type 'git'" + validation_failed=true + fi done if [[ "$validation_failed" == true ]]; then @@ -237,7 +250,7 @@ install_templates() { } build_source() { - local id type path repo docc_catalog source_dir + local id type path repo docc_catalog source_dir branch local entry="$1" id=$(echo "$entry" | jq -r '.id') @@ -245,8 +258,15 @@ build_source() { path=$(echo "$entry" | jq -r '.path // empty') repo=$(echo "$entry" | jq -r '.repo // empty') docc_catalog=$(echo "$entry" | jq -r '.docc_catalog // empty') + branch=$(echo "$entry" | jq -r '.branch // empty') + # Default to "main" when no branch is specified + if [[ -z "$branch" ]]; then + branch="main" + fi local is_combined is_combined=$(echo "$entry" | jq -r '.combined // false') + local add_docc_plugin + add_docc_plugin=$(echo "$entry" | jq -r '.add_docc_plugin // false') # Read per-source extra flags as a bash array (may be empty) local extra_flags=() @@ -283,18 +303,26 @@ build_source() { elif [[ "$type" == "git" ]]; then source_dir="$WORKSPACE/$id" if [[ -d "$source_dir/.git" ]]; then - echo "Updating existing clone..." - git -C "$source_dir" fetch --quiet origin - git -C "$source_dir" reset --quiet --hard origin/main + echo "Updating existing clone (branch: $branch)..." + git -C "$source_dir" fetch --quiet origin "$branch" + git -C "$source_dir" checkout --quiet "$branch" 2>/dev/null || git -C "$source_dir" checkout --quiet -b "$branch" "origin/$branch" + git -C "$source_dir" reset --quiet --hard "origin/$branch" else - echo "Cloning $repo..." - git clone --quiet --depth 1 "$repo" "$source_dir" + echo "Cloning $repo (branch: $branch)..." + git clone --quiet --branch "$branch" "$repo" "$source_dir" fi else echo "Error: unknown type '$type'" return 1 fi + # Inject swift-docc-plugin dependency if requested + if [[ "$add_docc_plugin" == "true" ]]; then + echo "Adding swift-docc-plugin dependency..." + (cd "$source_dir" && swift package add-dependency \ + https://github.com/swiftlang/swift-docc-plugin --from 1.1.0) + fi + # Build based on JSON configuration: # targets -> swift package generate-documentation --target # docc_catalog -> docc convert diff --git a/scripts/sources.json b/scripts/sources.json index 7d83f73..85f5982 100644 --- a/scripts/sources.json +++ b/scripts/sources.json @@ -6,6 +6,13 @@ "docc_catalog": "TSPL.docc", "combined": true }, + { + "id": "swift-migration-guide", + "type": "git", + "repo": "https://github.com/swiftlang/swift-migration-guide.git", + "docc_catalog": "Guide.docc", + "combined": true + }, { "id": "api-guidelines", "type": "local", @@ -20,12 +27,14 @@ "targets": ["LanguageGuides"], "combined": true }, - { - "id": "server-guides", - "type": "local", - "path": "server-guides", - "targets": ["ServerGuides"], - "combined": true + { + "id": "compiler-diagnostics", + "type": "git", + "repo": "https://github.com/swiftlang/swift.git", + "branch": "release/6.3", + "docc_catalog": "userdocs/diagnostics", + "combined": true, + "extra_flags": ["--allow-arbitrary-catalog-directories"] }, { "id": "ecosystem-tools", @@ -34,17 +43,11 @@ "targets": ["EcosystemTools"], "combined": true }, - { - "id": "swift-migration-guide", - "type": "git", - "repo": "https://github.com/swiftlang/swift-migration-guide.git", - "docc_catalog": "Guide.docc", - "combined": true - }, { "id": "docc-documentation", "type": "git", "repo": "https://github.com/swiftlang/swift-docc.git", + "branch": "release/6.3", "docc_catalog": "Sources/docc/DocCDocumentation.docc", "combined": true }, @@ -52,34 +55,38 @@ "id": "swiftpm", "type": "git", "repo": "https://github.com/swiftlang/swift-package-manager.git", + "branch": "release/6.3", "targets": ["PackageManagerDocs", "PackageDescription", "PackagePlugin"], "combined": true }, { - "id": "swiftly", + "id": "swift-testing", "type": "git", - "repo": "https://github.com/swiftlang/swiftly.git", - "targets": ["SwiftlyDocs"] + "repo": "https://github.com/swiftlang/swift-testing.git", + "branch": "release/6.3", + "targets": ["Testing"], + "add_docc_plugin": true, + "combined": true }, { - "id": "vscode-swift", + "id": "embedded-swift", "type": "git", - "repo": "https://github.com/swiftlang/vscode-swift.git", - "docc_catalog": "userdocs/userdocs.docc" + "repo": "https://github.com/swiftlang/swift-embedded-examples.git", + "docc_catalog": "Sources/EmbeddedSwift/Documentation.docc", + "combined": true }, - { - "id": "compiler-diagnostics", + { + "id": "swift-wasm", "type": "git", - "repo": "https://github.com/swiftlang/swift.git", - "docc_catalog": "userdocs/diagnostics", - "combined": true, - "extra_flags": ["--allow-arbitrary-catalog-directories"] + "repo": "https://github.com/swiftlang/swift-for-wasm-examples.git", + "targets": ["WasmGuide"], + "combined": true }, { - "id": "embedded-swift", - "type": "git", - "repo": "https://github.com/swiftlang/swift-embedded-examples.git", - "docc_catalog": "Sources/EmbeddedSwift/Documentation.docc", + "id": "server-guides", + "type": "local", + "path": "server-guides", + "targets": ["ServerGuides"], "combined": true }, { @@ -89,11 +96,16 @@ "docc_catalog": "SwiftServerTodos.docc", "combined": true }, - { - "id": "swift-wasm", + { + "id": "vscode-swift", "type": "git", - "repo": "https://github.com/swiftlang/swift-for-wasm-examples.git", - "targets": ["WasmGuide"], - "combined": true + "repo": "https://github.com/swiftlang/vscode-swift.git", + "docc_catalog": "userdocs/userdocs.docc" + }, + { + "id": "swiftly", + "type": "git", + "repo": "https://github.com/swiftlang/swiftly.git", + "targets": ["SwiftlyDocs"] } -] + ] From 3e37a719e0d7d3f32a666a247800f0fea99e3956 Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Thu, 12 Mar 2026 16:02:26 -0700 Subject: [PATCH 14/31] moving docc after swiftpm and testing --- scripts/sources.json | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/scripts/sources.json b/scripts/sources.json index 85f5982..6cecd50 100644 --- a/scripts/sources.json +++ b/scripts/sources.json @@ -43,14 +43,6 @@ "targets": ["EcosystemTools"], "combined": true }, - { - "id": "docc-documentation", - "type": "git", - "repo": "https://github.com/swiftlang/swift-docc.git", - "branch": "release/6.3", - "docc_catalog": "Sources/docc/DocCDocumentation.docc", - "combined": true - }, { "id": "swiftpm", "type": "git", @@ -68,6 +60,14 @@ "add_docc_plugin": true, "combined": true }, + { + "id": "docc-documentation", + "type": "git", + "repo": "https://github.com/swiftlang/swift-docc.git", + "branch": "release/6.3", + "docc_catalog": "Sources/docc/DocCDocumentation.docc", + "combined": true + }, { "id": "embedded-swift", "type": "git", From b67fd666e9f63e97396fa4a568ef70c2c6d07665 Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Thu, 12 Mar 2026 16:43:04 -0700 Subject: [PATCH 15/31] using Copyright from TSPL book for the common footer --- common/footer.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/common/footer.html b/common/footer.html index ab918d2..f757f8c 100644 --- a/common/footer.html +++ b/common/footer.html @@ -182,7 +182,7 @@

Governance

- Copyright © 2025 Apple Inc. All rights reserved. + Copyright © 2014–2026 Apple Inc. and the Swift project authors. All rights reserved.

Swift and the Swift logo are trademarks of Apple Inc. From 978a2b1f5f49dd766a9cb27aaf5f121a55efa9d7 Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Thu, 26 Mar 2026 13:22:37 -0700 Subject: [PATCH 16/31] efficiency check and better use of docc as an array instead of two items in a string --- scripts/build-docs.sh | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/scripts/build-docs.sh b/scripts/build-docs.sh index 5161475..6bf8f43 100755 --- a/scripts/build-docs.sh +++ b/scripts/build-docs.sh @@ -194,17 +194,13 @@ declare -a COMBINED_ARCHIVES=() declare -a COMBINED_EXPECTED_IDS=() # Find the docc tool — prefer xcrun on macOS, fall back to PATH. -# Resolved once and reused throughout. -resolve_docc_cmd() { - if command -v xcrun &>/dev/null && xcrun --find docc &>/dev/null 2>&1; then - echo "xcrun docc" - elif command -v docc &>/dev/null; then - echo "docc" - else - echo "" - fi -} -DOCC_CMD=$(resolve_docc_cmd) +# Resolved once as an array and reused throughout. +DOCC_CMD=() +if command -v xcrun &>/dev/null && xcrun --find docc &>/dev/null 2>&1; then + DOCC_CMD=(xcrun docc) +elif command -v docc &>/dev/null; then + DOCC_CMD=(docc) +fi # Find .doccarchive files produced by swift package generate-documentation. # They land in the .build directory tree; the exact path varies by toolchain. @@ -316,11 +312,15 @@ build_source() { return 1 fi - # Inject swift-docc-plugin dependency if requested + # Inject swift-docc-plugin dependency if requested and not already present if [[ "$add_docc_plugin" == "true" ]]; then - echo "Adding swift-docc-plugin dependency..." - (cd "$source_dir" && swift package add-dependency \ - https://github.com/swiftlang/swift-docc-plugin --from 1.1.0) + if ! grep -q 'swift-docc-plugin' "$source_dir/Package.swift"; then + echo "Adding swift-docc-plugin dependency..." + (cd "$source_dir" && swift package add-dependency \ + https://github.com/swiftlang/swift-docc-plugin --from 1.1.0) + else + echo "swift-docc-plugin dependency already present, skipping." + fi fi # Build based on JSON configuration: @@ -374,7 +374,7 @@ build_source() { return 1 fi - if [[ -z "$DOCC_CMD" ]]; then + if [[ ${#DOCC_CMD[@]} -eq 0 ]]; then echo "Error: 'docc' tool not found (tried xcrun and PATH)" return 1 fi @@ -386,7 +386,7 @@ build_source() { echo "Converting catalog with docc convert..." rm -rf "$output_path" - $DOCC_CMD convert "$catalog_path" --output-path "$output_path" \ + "${DOCC_CMD[@]}" convert "$catalog_path" --output-path "$output_path" \ "${DOCC_BUILD_FLAGS[@]}" \ ${extra_flags[@]+"${extra_flags[@]}"} @@ -450,7 +450,7 @@ if [[ ${#COMBINED_EXPECTED_IDS[@]} -gt 0 && -z "$ONLY" ]]; then echo "Error: no combined archives were produced despite all sources succeeding" FAILED+=("combined-merge") - elif [[ -z "$DOCC_CMD" ]]; then + elif [[ ${#DOCC_CMD[@]} -eq 0 ]]; then echo "Error: 'docc' tool not found, cannot merge archives" FAILED+=("combined-merge") @@ -478,7 +478,7 @@ if [[ ${#COMBINED_EXPECTED_IDS[@]} -gt 0 && -z "$ONLY" ]]; then echo " - $(basename "$a")" done - if $DOCC_CMD merge "${COMBINED_ARCHIVES[@]}" \ + if "${DOCC_CMD[@]}" merge "${COMBINED_ARCHIVES[@]}" \ --output-path "$COMBINED_OUTPUT"; then echo "Combined archive: $COMBINED_OUTPUT" SUCCEEDED+=("combined-merge") From c76383d954aec60ad124bf91a498b1cf14096f9c Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Thu, 26 Mar 2026 14:07:19 -0700 Subject: [PATCH 17/31] building them all combined, exporting a manifest of what branches were built alongside the output --- scripts/build-docs.sh | 189 ++++++++++++++++++++++++++++-------------- scripts/sources.json | 53 +++++------- 2 files changed, 148 insertions(+), 94 deletions(-) diff --git a/scripts/build-docs.sh b/scripts/build-docs.sh index 6bf8f43..285af0e 100755 --- a/scripts/build-docs.sh +++ b/scripts/build-docs.sh @@ -5,9 +5,9 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" ROOT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)" SOURCES_FILE="$SCRIPT_DIR/sources.json" -# NOTE: The order of the archives in sources.json matters for merging into a combined archive, +# NOTE: The order of the archives in sources.json matters for merging into a combined archive, # as they're listed in the order they are merged, which is driven (in this script) -# by the ordering in the JSON. +# by the ordering in the JSON. All sources are included in the combined archive. # Ensure consistent, pretty-printed DocC JSON output export DOCC_JSON_PRETTYPRINT=YES @@ -28,6 +28,7 @@ OUTPUT_DIR="$ROOT_DIR/.build-output" WORKSPACE="$ROOT_DIR/.workspace" CLEAN=false ONLY="" +BRANCH="" usage() { cat < Where to export built archives (default: .build-output/) - --workspace Where to clone external repos (default: .workspace/) - --clean Remove workspace and re-clone everything - --only Build only a specific source by id - -h, --help Show this help message + --output-dir Where to export built archives (default: .build-output/) + --workspace Where to clone external repos (default: .workspace/) + --clean Remove workspace and re-clone everything + --only Build only a specific source by id + --branch Use this branch for git sources that have it (e.g. release/6.3). + Falls back to 'main' unless source has 'fallback_branch' set. + -h, --help Show this help message EOF } @@ -63,6 +66,10 @@ while [[ $# -gt 0 ]]; do ONLY="$2" shift 2 ;; + --branch) + BRANCH="$2" + shift 2 + ;; -h|--help) usage exit 0 @@ -101,18 +108,34 @@ for tmpl in "${TEMPLATE_FILES[@]}"; do fi done +# Check whether a remote repository has a given branch (refs only, no data transfer). +remote_has_branch() { + local repo_url="$1" + local branch_name="$2" + git ls-remote --heads "$repo_url" "$branch_name" 2>/dev/null | grep -q . +} + +# Find the latest release/* branch in a remote repository (version-sorted). +# Returns the full branch name (e.g. "release/1.1") or empty string if none. +latest_release_branch() { + local repo_url="$1" + git ls-remote --heads "$repo_url" "release/*" 2>/dev/null \ + | sed 's|.*refs/heads/||' \ + | sort -t/ -k2 -V \ + | tail -n 1 +} + # Validate all source entries before doing any work validate_sources() { local validation_failed=false for i in $(seq 0 $((source_count - 1))); do - local entry entry_id entry_type entry_path entry_repo entry_branch has_targets has_docc_catalog label + local entry entry_id entry_type entry_path entry_repo has_targets has_docc_catalog label entry=$(jq ".[$i]" "$SOURCES_FILE") entry_id=$(echo "$entry" | jq -r '.id // empty') entry_type=$(echo "$entry" | jq -r '.type // empty') entry_path=$(echo "$entry" | jq -r '.path // empty') entry_repo=$(echo "$entry" | jq -r '.repo // empty') - entry_branch=$(echo "$entry" | jq -r '.branch // empty') has_targets=$(echo "$entry" | jq 'has("targets")') has_docc_catalog=$(echo "$entry" | jq 'has("docc_catalog")') @@ -154,17 +177,19 @@ validate_sources() { validation_failed=true fi - if [[ -n "$entry_branch" && "$entry_type" != "git" ]]; then - echo "Validation error: $label has 'branch' but is not type 'git'" - validation_failed=true - fi - local add_docc_plugin add_docc_plugin=$(echo "$entry" | jq -r '.add_docc_plugin // false') if [[ "$add_docc_plugin" == "true" && "$entry_type" != "git" ]]; then echo "Validation error: $label has 'add_docc_plugin' but is not type 'git'" validation_failed=true fi + + local fallback_branch + fallback_branch=$(echo "$entry" | jq -r '.fallback_branch // empty') + if [[ -n "$fallback_branch" && "$entry_type" != "git" ]]; then + echo "Validation error: $label has 'fallback_branch' but is not type 'git'" + validation_failed=true + fi done if [[ "$validation_failed" == true ]]; then @@ -191,7 +216,7 @@ mkdir -p "$OUTPUT_DIR" "$WORKSPACE" declare -a SUCCEEDED=() declare -a FAILED=() declare -a COMBINED_ARCHIVES=() -declare -a COMBINED_EXPECTED_IDS=() +declare -a MANIFEST_ENTRIES=() # Find the docc tool — prefer xcrun on macOS, fall back to PATH. # Resolved once as an array and reused throughout. @@ -246,7 +271,9 @@ install_templates() { } build_source() { - local id type path repo docc_catalog source_dir branch + local id type path repo docc_catalog source_dir + local actual_branch="main" + local fallback_used=false local entry="$1" id=$(echo "$entry" | jq -r '.id') @@ -254,13 +281,35 @@ build_source() { path=$(echo "$entry" | jq -r '.path // empty') repo=$(echo "$entry" | jq -r '.repo // empty') docc_catalog=$(echo "$entry" | jq -r '.docc_catalog // empty') - branch=$(echo "$entry" | jq -r '.branch // empty') - # Default to "main" when no branch is specified - if [[ -z "$branch" ]]; then - branch="main" + + # Determine which branch to use for git sources + if [[ "$type" == "git" && -n "$BRANCH" ]]; then + if remote_has_branch "$repo" "$BRANCH"; then + actual_branch="$BRANCH" + else + local fallback_branch + fallback_branch=$(echo "$entry" | jq -r '.fallback_branch // empty') + + if [[ "$fallback_branch" == "latest-release" ]]; then + local detected + detected=$(latest_release_branch "$repo") + if [[ -n "$detected" ]]; then + echo " Note: $repo does not have branch '$BRANCH', using latest release branch '$detected'" + actual_branch="$detected" + else + echo " Note: $repo does not have branch '$BRANCH' and no release branches found, falling back to 'main'" + actual_branch="main" + fi + elif [[ -n "$fallback_branch" ]]; then + echo " Note: $repo does not have branch '$BRANCH', using fallback branch '$fallback_branch'" + actual_branch="$fallback_branch" + else + echo " Note: $repo does not have branch '$BRANCH', falling back to 'main'" + actual_branch="main" + fi + fallback_used=true + fi fi - local is_combined - is_combined=$(echo "$entry" | jq -r '.combined // false') local add_docc_plugin add_docc_plugin=$(echo "$entry" | jq -r '.add_docc_plugin // false') @@ -299,13 +348,13 @@ build_source() { elif [[ "$type" == "git" ]]; then source_dir="$WORKSPACE/$id" if [[ -d "$source_dir/.git" ]]; then - echo "Updating existing clone (branch: $branch)..." - git -C "$source_dir" fetch --quiet origin "$branch" - git -C "$source_dir" checkout --quiet "$branch" 2>/dev/null || git -C "$source_dir" checkout --quiet -b "$branch" "origin/$branch" - git -C "$source_dir" reset --quiet --hard "origin/$branch" + echo "Updating existing clone (branch: $actual_branch)..." + git -C "$source_dir" fetch --quiet origin "$actual_branch" + git -C "$source_dir" checkout --quiet "$actual_branch" 2>/dev/null || git -C "$source_dir" checkout --quiet -b "$actual_branch" "origin/$actual_branch" + git -C "$source_dir" reset --quiet --hard "origin/$actual_branch" else - echo "Cloning $repo (branch: $branch)..." - git clone --quiet --branch "$branch" "$repo" "$source_dir" + echo "Cloning $repo (branch: $actual_branch)..." + git clone --quiet --branch "$actual_branch" "$repo" "$source_dir" fi else echo "Error: unknown type '$type'" @@ -361,9 +410,7 @@ build_source() { rm -rf "${OUTPUT_DIR:?}/${output_name}.doccarchive" cp -R "$archive" "$OUTPUT_DIR/${output_name}.doccarchive" - if [[ "$is_combined" == "true" ]]; then - COMBINED_ARCHIVES+=("$OUTPUT_DIR/${output_name}.doccarchive") - fi + COMBINED_ARCHIVES+=("$OUTPUT_DIR/${output_name}.doccarchive") done else @@ -390,11 +437,26 @@ build_source() { "${DOCC_BUILD_FLAGS[@]}" \ ${extra_flags[@]+"${extra_flags[@]}"} - if [[ "$is_combined" == "true" ]]; then - COMBINED_ARCHIVES+=("$output_path") - fi + COMBINED_ARCHIVES+=("$output_path") fi + # Record manifest entry + local commit_sha="" + if [[ "$type" == "git" ]]; then + commit_sha=$(git -C "$source_dir" rev-parse HEAD 2>/dev/null || echo "unknown") + elif [[ "$type" == "local" ]]; then + actual_branch=$(git -C "$source_dir" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown") + commit_sha=$(git -C "$source_dir" rev-parse HEAD 2>/dev/null || echo "unknown") + fi + + MANIFEST_ENTRIES+=("$(jq -n \ + --arg id "$id" \ + --arg type "$type" \ + --arg actual "$actual_branch" \ + --argjson fallback "$fallback_used" \ + --arg commit "$commit_sha" \ + '{id: $id, type: $type, actual_branch: $actual, fallback_used: $fallback, commit: $commit}')") + echo "Done: $id" } @@ -408,12 +470,6 @@ for i in $(seq 0 $((source_count - 1))); do continue fi - is_combined=$(echo "$entry" | jq -r '.combined // false') - - if [[ "$is_combined" == "true" ]]; then - COMBINED_EXPECTED_IDS+=("$entry_id") - fi - if build_source "$entry"; then SUCCEEDED+=("$entry_id") else @@ -421,35 +477,21 @@ for i in $(seq 0 $((source_count - 1))); do fi done -# Merge combined archives — only if all combined sources built successfully -if [[ ${#COMBINED_EXPECTED_IDS[@]} -gt 0 && -z "$ONLY" ]]; then +# Merge all archives — only when building everything (not --only) +if [[ ${#COMBINED_ARCHIVES[@]} -gt 0 && -z "$ONLY" ]]; then echo "" echo "========================================" echo "Merging combined documentation archive" echo "========================================" - # Check that no combined source appears in the FAILED list - combined_failures=() - for cid in "${COMBINED_EXPECTED_IDS[@]}"; do - for fid in ${FAILED[@]+"${FAILED[@]}"}; do - if [[ "$cid" == "$fid" ]]; then - combined_failures+=("$cid") - fi - done - done - - if [[ ${#combined_failures[@]} -gt 0 ]]; then - echo "Error: cannot merge — the following combined sources failed to build:" - for cf in "${combined_failures[@]}"; do - echo " - $cf" + if [[ ${#FAILED[@]} -gt 0 ]]; then + echo "Error: cannot merge — the following sources failed to build:" + for fid in "${FAILED[@]}"; do + echo " - $fid" done echo "Skipping merge step." FAILED+=("combined-merge") - elif [[ ${#COMBINED_ARCHIVES[@]} -eq 0 ]]; then - echo "Error: no combined archives were produced despite all sources succeeding" - FAILED+=("combined-merge") - elif [[ ${#DOCC_CMD[@]} -eq 0 ]]; then echo "Error: 'docc' tool not found, cannot merge archives" FAILED+=("combined-merge") @@ -490,6 +532,27 @@ if [[ ${#COMBINED_EXPECTED_IDS[@]} -gt 0 && -z "$ONLY" ]]; then fi fi +# Generate build manifest +if [[ ${#MANIFEST_ENTRIES[@]} -gt 0 ]]; then + MANIFEST_FILE="$OUTPUT_DIR/build-manifest.json" + sources_json="[" + for idx in "${!MANIFEST_ENTRIES[@]}"; do + if [[ $idx -gt 0 ]]; then + sources_json+="," + fi + sources_json+="${MANIFEST_ENTRIES[$idx]}" + done + sources_json+="]" + + jq -n \ + --arg build_time "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \ + --arg branch "$BRANCH" \ + --argjson sources "$sources_json" \ + '{build_time: $build_time, branch: $branch, sources: $sources}' \ + > "$MANIFEST_FILE" + echo "Build manifest: $MANIFEST_FILE" +fi + # Summary echo "" echo "========================================" @@ -498,6 +561,12 @@ echo "========================================" echo "Succeeded (${#SUCCEEDED[@]}): ${SUCCEEDED[*]:-none}" echo "Failed (${#FAILED[@]}): ${FAILED[*]:-none}" echo "Output: $OUTPUT_DIR" +if [[ -n "$BRANCH" ]]; then + echo "Branch: $BRANCH" +fi +if [[ -f "$OUTPUT_DIR/build-manifest.json" ]]; then + echo "Manifest: $OUTPUT_DIR/build-manifest.json" +fi if [[ ${#FAILED[@]} -gt 0 ]]; then exit 1 diff --git a/scripts/sources.json b/scripts/sources.json index 6cecd50..a4b79e9 100644 --- a/scripts/sources.json +++ b/scripts/sources.json @@ -3,109 +3,94 @@ "id": "swift-book", "type": "git", "repo": "https://github.com/swiftlang/swift-book.git", - "docc_catalog": "TSPL.docc", - "combined": true + "docc_catalog": "TSPL.docc" }, { "id": "swift-migration-guide", "type": "git", "repo": "https://github.com/swiftlang/swift-migration-guide.git", - "docc_catalog": "Guide.docc", - "combined": true + "docc_catalog": "Guide.docc" }, { "id": "api-guidelines", "type": "local", "path": "api-guidelines", - "targets": ["APIGuidelines"], - "combined": true + "targets": ["APIGuidelines"] }, { "id": "language-guides", "type": "local", "path": "language-guides", - "targets": ["LanguageGuides"], - "combined": true + "targets": ["LanguageGuides"] }, - { + { "id": "compiler-diagnostics", "type": "git", "repo": "https://github.com/swiftlang/swift.git", - "branch": "release/6.3", "docc_catalog": "userdocs/diagnostics", - "combined": true, "extra_flags": ["--allow-arbitrary-catalog-directories"] }, { "id": "ecosystem-tools", "type": "local", "path": "ecosystem-tools", - "targets": ["EcosystemTools"], - "combined": true + "targets": ["EcosystemTools"] }, { "id": "swiftpm", "type": "git", "repo": "https://github.com/swiftlang/swift-package-manager.git", - "branch": "release/6.3", - "targets": ["PackageManagerDocs", "PackageDescription", "PackagePlugin"], - "combined": true + "targets": ["PackageManagerDocs", "PackageDescription", "PackagePlugin"] }, { "id": "swift-testing", "type": "git", "repo": "https://github.com/swiftlang/swift-testing.git", - "branch": "release/6.3", "targets": ["Testing"], - "add_docc_plugin": true, - "combined": true + "add_docc_plugin": true }, { "id": "docc-documentation", "type": "git", "repo": "https://github.com/swiftlang/swift-docc.git", - "branch": "release/6.3", - "docc_catalog": "Sources/docc/DocCDocumentation.docc", - "combined": true + "docc_catalog": "Sources/docc/DocCDocumentation.docc" }, { "id": "embedded-swift", "type": "git", "repo": "https://github.com/swiftlang/swift-embedded-examples.git", - "docc_catalog": "Sources/EmbeddedSwift/Documentation.docc", - "combined": true + "docc_catalog": "Sources/EmbeddedSwift/Documentation.docc" }, - { + { "id": "swift-wasm", "type": "git", "repo": "https://github.com/swiftlang/swift-for-wasm-examples.git", - "targets": ["WasmGuide"], - "combined": true + "targets": ["WasmGuide"] }, { "id": "server-guides", "type": "local", "path": "server-guides", - "targets": ["ServerGuides"], - "combined": true + "targets": ["ServerGuides"] }, { "id": "swift-server-todos-tutorial", "type": "git", "repo": "https://github.com/swiftlang/swift-server-todos-tutorial.git", - "docc_catalog": "SwiftServerTodos.docc", - "combined": true + "docc_catalog": "SwiftServerTodos.docc" }, { "id": "vscode-swift", "type": "git", "repo": "https://github.com/swiftlang/vscode-swift.git", - "docc_catalog": "userdocs/userdocs.docc" + "docc_catalog": "userdocs/userdocs.docc", + "fallback_branch": "latest-release" }, { "id": "swiftly", "type": "git", "repo": "https://github.com/swiftlang/swiftly.git", - "targets": ["SwiftlyDocs"] + "targets": ["SwiftlyDocs"], + "fallback_branch": "latest-release" } - ] +] From 2da9947e9fc79a4e6f195f1e4978699a5a4437c1 Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Thu, 26 Mar 2026 14:39:10 -0700 Subject: [PATCH 18/31] enabling specific prep work per repo (needed for swift-book) --- scripts/build-docs.sh | 15 +++++++++++++++ scripts/sources.json | 3 ++- 2 files changed, 17 insertions(+), 1 deletion(-) diff --git a/scripts/build-docs.sh b/scripts/build-docs.sh index 285af0e..5fa6b73 100755 --- a/scripts/build-docs.sh +++ b/scripts/build-docs.sh @@ -190,6 +190,13 @@ validate_sources() { echo "Validation error: $label has 'fallback_branch' but is not type 'git'" validation_failed=true fi + + local preflight + preflight=$(echo "$entry" | jq -r '.preflight // empty') + if [[ "$(echo "$entry" | jq 'has("preflight")')" == "true" && -z "$preflight" ]]; then + echo "Validation error: $label has 'preflight' but it is empty" + validation_failed=true + fi done if [[ "$validation_failed" == true ]]; then @@ -361,6 +368,14 @@ build_source() { return 1 fi + # Run preflight command if configured + local preflight + preflight=$(echo "$entry" | jq -r '.preflight // empty') + if [[ -n "$preflight" ]]; then + echo "Running preflight: $preflight" + (cd "$source_dir" && bash -c "$preflight") + fi + # Inject swift-docc-plugin dependency if requested and not already present if [[ "$add_docc_plugin" == "true" ]]; then if ! grep -q 'swift-docc-plugin' "$source_dir/Package.swift"; then diff --git a/scripts/sources.json b/scripts/sources.json index a4b79e9..e156e1b 100644 --- a/scripts/sources.json +++ b/scripts/sources.json @@ -3,7 +3,8 @@ "id": "swift-book", "type": "git", "repo": "https://github.com/swiftlang/swift-book.git", - "docc_catalog": "TSPL.docc" + "docc_catalog": "TSPL.docc", + "preflight": "bin/generate-grammar" }, { "id": "swift-migration-guide", From 4c2af6f37b7989360da6ce4eb4ab69b7bfaab6ba Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Fri, 3 Apr 2026 11:19:19 -0700 Subject: [PATCH 19/31] Add license headers and .licenseignore to pass CI checks Add Apache 2.0 license headers to all _empty.swift files and build-docs.sh. Add .licenseignore to exclude files that cannot have license headers (Package.swift, .gitkeep, .html, README). Configure license_header_check_project_name in CI workflow. --- scripts/build-docs.sh | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/scripts/build-docs.sh b/scripts/build-docs.sh index 5fa6b73..d8628c5 100755 --- a/scripts/build-docs.sh +++ b/scripts/build-docs.sh @@ -1,4 +1,17 @@ #!/bin/bash +##===----------------------------------------------------------------------===## +## +## This source file is part of the Swift.org open source project +## +## Copyright (c) 2026 Apple Inc. and the Swift.org project authors +## Licensed under Apache License v2.0 +## +## See LICENSE.txt for license information +## See CONTRIBUTORS.txt for the list of Swift.org project authors +## +## SPDX-License-Identifier: Apache-2.0 +## +##===----------------------------------------------------------------------===## set -euo pipefail SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" From bd8e760e77bd5acda71310058f5733749ef84c6e Mon Sep 17 00:00:00 2001 From: Joe Heck Date: Fri, 3 Apr 2026 11:50:47 -0700 Subject: [PATCH 20/31] Add license headers to HTML files and trim .licenseignore --- common/footer.html | 9 +++++++++ common/header.html | 9 +++++++++ 2 files changed, 18 insertions(+) diff --git a/common/footer.html b/common/footer.html index f757f8c..3f71c54 100644 --- a/common/footer.html +++ b/common/footer.html @@ -1,3 +1,12 @@ +