Merge pull request #2096 from ahoppen/ahoppen/verify-documentation

Add subcommand to swift-syntax-dev-utils to verify that documentation builds without errors or warnings

Author: ahoppen

CodeGeneration/Sources/SyntaxSupport/PatternNodes.swift

@@ -212,7 +212,7 @@ public let PATTERN_NODES: [Node] = [
 
       ### Examples
 
-      ``WildcardPattern`` matches and ignores any value.
+      ``WildcardPatternSyntax`` matches and ignores any value.
       For example `_` in the example:
 
       ```swift

Sources/SwiftParser/ParseSourceFile.swift

@@ -117,7 +117,7 @@ extension Parser {
   /// Parse the source code in the given buffer as Swift source file with support
   /// for incremental parsing.
   ///
-  /// See doc comments in ``Parser/parseIncrementally(source:parseTransition:)-4kn2k``
+  /// See doc comments in ``Parser/parseIncrementally(source:parseTransition:)-dj0z``
   public static func parseIncrementally(
     source: UnsafeBufferPointer<UInt8>,
     maximumNestingLevel: Int? = nil,

Sources/SwiftSyntax/generated/syntaxNodes/SyntaxNodesTUVWXYZ.swift

@@ -4238,7 +4238,7 @@ public struct WhileStmtSyntax: StmtSyntaxProtocol, SyntaxHashable, _LeafStmtSynt
 /// 
 /// ### Examples
 /// 
-/// ``WildcardPattern`` matches and ignores any value.
+/// ``WildcardPatternSyntax`` matches and ignores any value.
 /// For example `_` in the example:
 /// 
 /// ```swift

SwiftSyntaxDevUtils/Package.swift

@@ -6,7 +6,7 @@ import PackageDescription
 let package = Package(
   name: "swift-syntax-dev-utils",
   platforms: [
-    .macOS(.v10_15)
+    .macOS(.v13)
   ],
   products: [
     .executable(name: "swift-syntax-dev-utils", targets: ["swift-syntax-dev-utils"])

SwiftSyntaxDevUtils/Sources/swift-syntax-dev-utils/SwiftSyntaxDevUtils.swift

@@ -29,6 +29,7 @@ struct SwiftSyntaxDevUtils: ParsableCommand {
       Format.self,
       GenerateSourceCode.self,
       Test.self,
+      VerifyDocumentation.self,
       VerifySourceCode.self,
     ]
   )

SwiftSyntaxDevUtils/Sources/swift-syntax-dev-utils/commands/VerifyDocumentation.swift

@@ -0,0 +1,67 @@
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2014 - 2023 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 the list of Swift project authors
+//
+//===----------------------------------------------------------------------===//
+
+import ArgumentParser
+import Foundation
+import RegexBuilder
+
+struct VerifyDocumentation: ParsableCommand {
+  static var configuration: CommandConfiguration {
+    CommandConfiguration(
+      abstract: "Verify that the docc documentation builds without warnings or errors."
+    )
+  }
+
+  @Flag(help: "Enable verbose logging.")
+  var verbose: Bool = false
+
+  func targetsInSwiftPackageIndexManifest() throws -> [String] {
+    let extractTargetRegex = Regex {
+      #/^      - /#
+      Capture(ZeroOrMore(.word))
+      #/$/#
+    }
+    let spiYmlFile = Paths.packageDir.appendingPathComponent(".spi.yml")
+    let spiYmlFileContents = try String(contentsOf: spiYmlFile)
+    return
+      spiYmlFileContents
+      .components(separatedBy: "\n")
+      .filter({ !$0.matches(of: extractTargetRegex).isEmpty })
+      .map { $0.replacing(extractTargetRegex) { $0.1 } }
+      .sorted()
+  }
+
+  func run() throws {
+    for target in try targetsInSwiftPackageIndexManifest() {
+      try buildDocumentation(product: target)
+    }
+  }
+
+  func buildDocumentation(product: String) throws {
+    guard let xcodebuildExec = try? Paths.xcodebuildExec else {
+      return
+    }
+    logSection("Building documentation for \(product)")
+    try ProcessRunner(
+      executableURL: xcodebuildExec,
+      arguments: [
+        "docbuild",
+        "-workspace",
+        Paths.packageDir.path,
+        "-scheme",
+        product,
+        "-destination", "platform=macOS",
+        "OTHER_DOCC_FLAGS='--warnings-as-errors'",
+      ]
+    ).run(captureStdout: false, captureStderr: false, verbose: self.verbose)
+  }
+}