Add DocC to SwiftSyntax

Author: kimdv

Package.swift

@@ -37,6 +37,7 @@ if let parserLibSearchPath = ProcessInfo.processInfo.environment["SWIFT_SYNTAX_P
 
 let package = Package(
   name: "SwiftSyntax",
+  defaultLocalization: "en",
   products: [
     .library(name: "SwiftSyntax", type: .static, targets: ["SwiftSyntax"]),
     .library(name: "SwiftSyntaxParser", type: .static, targets: ["SwiftSyntaxParser"]),
@@ -143,3 +144,10 @@ let package = Package(
     ),
   ]
 )
+
+// SwiftPM command plugins are only supported by Swift version 5.6 and later.
+#if swift(>=5.6)
+package.dependencies += [
+    .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"),
+]
+#endif

Sources/SwiftSyntax/Documentation.docc/Documentation.md

@@ -0,0 +1,8 @@
+# ``SwiftSyntax``
+
+SwiftSyntax is a set of Swift bindings for the
+[libSyntax](https://github.com/apple/swift/tree/main/lib/Syntax) library. It
+allows Swift tools to parse, inspect, generate, and transform Swift source
+code.
+
+Its API is designed for performance-critical applications. It uses value types almost exclusively and aims to avoid existential conversions where possible.

utils/update-gh-pages-documentation-site.sh

@@ -0,0 +1,86 @@
+#!/bin/bash
+#
+# This source file is part of the Swift.org open source project
+#
+# Copyright (c) 2022 Apple Inc. and the Swift project authors
+# Licensed under Apache License v2.0 with Runtime Library Exception
+#
+# See https://swift.org/LICENSE.txt for license information
+# See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+#
+# Updates the GitHub Pages documentation site thats published from the 'docs' 
+# subdirectory in the 'gh-pages' branch of this repository.
+#
+# This script should be run by someone with commit access to the 'gh-pages' branch
+# at a regular frequency so that the documentation content on the GitHub Pages site
+# is up-to-date with the content in this repo.
+#
+
+set -eu
+
+# A `realpath` alternative using the default C implementation.
+filepath() {
+  [[ $1 = /* ]] && echo "$1" || echo "$PWD/${1#./}"
+}
+
+SWIFT_SYNTAX_ROOT="$(dirname $(dirname $(filepath $0)))"
+
+SWIFT_SYNTAX_BUILD_DIR="$SWIFT_SYNTAX_ROOT"/.build/swift-syntax-gh-pages-build
+SWIFT_SYNTAX_BUILDER_OUTPUT_DIR="$SWIFT_SYNTAX_BUILD_DIR"/swift-syntax-builder-docs
+
+mkdir -p "$SWIFT_SYNTAX_BUILDER_OUTPUT_DIR"
+
+# Set current directory to the repository root
+cd "$SWIFT_SYNTAX_ROOT"
+
+# Use git worktree to checkout the gh-pages branch of this repository in a gh-pages sub-directory
+git fetch
+git worktree add --checkout gh-pages origin/gh-pages
+
+# Pretty print DocC JSON output so that it can be consistently diffed between commits
+export DOCC_JSON_PRETTYPRINT="YES"
+
+# Generate documentation for the 'SwiftSyntax' target and output it
+# to the /docs subdirectory in the gh-pages worktree directory.
+swift package \
+    --allow-writing-to-directory "$SWIFT_SYNTAX_ROOT/gh-pages/docs" \
+    generate-documentation \
+    --target SwiftSyntax \
+    --disable-indexing \
+    --transform-for-static-hosting \
+    --hosting-base-path swift-syntax \
+    --output-path "$SWIFT_SYNTAX_ROOT/gh-pages/docs"
+
+# Generate documentation for the 'SwiftSyntaxBuilder' target and output it
+# to a temporary output directory in the .build directory.
+swift package \
+    --allow-writing-to-directory "$SWIFT_SYNTAX_BUILD_DIR" \
+    generate-documentation \
+    --target SwiftSyntaxBuilder \
+    --disable-indexing \
+    --transform-for-static-hosting \
+    --hosting-base-path swift-syntax \
+    --output-path "$SWIFT_SYNTAX_BUILDER_OUTPUT_DIR"
+
+# Merge the SwiftSyntaxBuilder docs into the primary SwiftSyntax docs
+cp -R "$SWIFT_SYNTAX_BUILDER_OUTPUT_DIR"/* "$SWIFT_SYNTAX_ROOT/gh-pages/docs/"
+
+# Save the current commit we've just built documentation from in a variable
+CURRENT_COMMIT_HASH=`git rev-parse --short HEAD`
+
+# Commit and push our changes to the gh-pages branch
+cd gh-pages
+git add docs
+
+if [ -n "$(git status --porcelain)" ]; then
+    echo "Documentation changes found. Commiting the changes to the 'gh-pages' branch and pushing to origin."
+    git commit -m "Update GitHub Pages documentation site to $CURRENT_COMMIT_HASH"
+    git push origin HEAD:gh-pages
+else
+  # No changes found, nothing to commit.
+  echo "No documentation changes found."
+fi
+
+# Delete the git worktree we created
+cd ..
+git worktree remove gh-pages