Add flag to enable combined documentation support

This flag allows the targets to link to each other
and creates an additional combined archive.

rdar://116698361

Author: d-ronnqvist

Plugins/Swift-DocC Convert/SwiftDocCConvert.swift

@@ -30,6 +30,7 @@ import PackagePlugin
         }
 
         let verbose = argumentExtractor.extractFlag(named: "verbose") > 0
+        let isCombinedDocumentationEnabled = argumentExtractor.extractFlag(named: PluginFlag.enableCombinedDocumentationSupportFlagName) > 0
 
         // Parse the given command-line arguments
         let parsedArguments = ParsedArguments(argumentExtractor.remainingArguments)
@@ -100,14 +101,22 @@ import PackagePlugin
             // arguments to pass to `docc`. ParsedArguments will merge the flags provided
             // by the user with default fallback values for required flags that were not
             // provided.
-            let doccArguments = parsedArguments.doccArguments(
+            var doccArguments = parsedArguments.doccArguments(
                 action: .convert,
                 targetKind: target.kind == .executable ? .executable : .library,
                 doccCatalogPath: target.doccCatalogPath,
                 targetName: target.name,
                 symbolGraphDirectoryPath: symbolGraphs.unifiedSymbolGraphsDirectory.path,
                 outputPath: doccArchiveOutputPath
             )
+            if isCombinedDocumentationEnabled {
+                doccArguments.append(CommandLineOption.enableExternalLinkSupport.defaultName)
+                
+                for taskDependency in task.dependencies {
+                    let dependencyArchivePath = taskDependency.target.doccArchiveOutputPath(in: context)
+                    doccArguments.append(contentsOf: [CommandLineOption.externalLinkDependency.defaultName, dependencyArchivePath])
+                }
+            }
 
             if verbose {
                 let arguments = doccArguments.joined(separator: " ")
@@ -171,9 +180,31 @@ import PackagePlugin
         queue.addOperations(operations, waitUntilFinished: true)
 
         if documentationArchives.count > 1 {
+            documentationArchives = documentationArchives.sorted(by: { $0.lastPathComponent < $1.lastPathComponent })
+            
+            if isCombinedDocumentationEnabled {
+                // Merge the archives into a combined archive
+                let combinedArchiveName = "Combined \(context.package.displayName) Documentation.doccarchive"
+                let combinedArchiveOutput = URL(fileURLWithPath: context.pluginWorkDirectory.appending(combinedArchiveName).string)
+                
+                var mergeCommandArguments = ["merge"]
+                mergeCommandArguments.append(contentsOf: documentationArchives.map(\.standardizedFileURL.path))
+                mergeCommandArguments.append(contentsOf: ["--output-path", combinedArchiveOutput.path])
+                
+                // Remove the combined archive if it already exists
+                try? FileManager.default.removeItem(at: combinedArchiveOutput)
+                
+                // Create a new combined archive
+                let process = try Process.run(doccExecutableURL, arguments: mergeCommandArguments)
+                process.waitUntilExit()
+                
+                // Display the combined archive before the other generated archives
+                documentationArchives.insert(combinedArchiveOutput, at: 0)
+            }
+            
             print("""
             Generated \(documentationArchives.count) DocC archives in '\(context.pluginWorkDirectory.string)':
-              \(documentationArchives.map(\.lastPathComponent).sorted().joined(separator: "\n  "))
+              \(documentationArchives.map(\.lastPathComponent).joined(separator: "\n  "))
             """)
         }
     }

Sources/SwiftDocCPluginUtilities/CommandLineOptions/CommandLineOption.swift

@@ -59,4 +59,15 @@ extension CommandLineOption {
     static let fallbackDefaultModuleKind = CommandLineOption(
         defaultName: "--fallback-default-module-kind"
     )
+    
+    /// A DocC flag that enables support for linking to other DocC archives and enables 
+    /// other documentation builds to link to the generated DocC archive.
+    static let enableExternalLinkSupport = CommandLineOption(
+        defaultName: "--enable-experimental-external-link-support"
+    )
+    
+    /// A DocC flag that specifies a dependency DocC archive that the current build can link to.
+    static let externalLinkDependency = CommandLineOption(
+        defaultName: "--dependency"
+    )
 }

Sources/SwiftDocCPluginUtilities/HelpInformation.swift

@@ -48,12 +48,17 @@ public enum HelpInformation {
             PluginFlag.skipSynthesizedSymbols
         ]
 
+        let doccFeatures = (try? DocCFeatures(doccExecutable: doccExecutableURL)) ?? .init()
+        
         // stops 'not mutated' warning for Swift 5.7 and lower
         supportedPluginFlags += []
 
 #if swift(>=5.8)
         supportedPluginFlags += [PluginFlag.extendedTypes]
 #endif
+        if doccFeatures.contains(.linkDependencies) {
+            supportedPluginFlags += [PluginFlag.enableCombinedDocumentationSupport]
+        }
 
         for flag in supportedPluginFlags {
             var flagListText = flag.positive.parsedValues.sorted().joined(separator: ", ")

Sources/SwiftDocCPluginUtilities/PluginFlags/EnableCombinedDocumentationSupportFlag.swift

@@ -0,0 +1,27 @@
+// This source file is part of the Swift.org open source project
+//
+// Copyright (c) 2024 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
+
+extension PluginFlag {
+    /// Create a combined DocC archive containing documentation for all built targets.
+    ///
+    /// - Note: This flag requires that the `docc` executable supports ``Feature/linkDependencies``.
+    static let enableCombinedDocumentationSupport = PluginFlag(
+        parsedValues: [
+            "--\(enableCombinedDocumentationSupportFlagName)"
+        ],
+        abstract: "Create a combined DocC archive with all generated documentation",
+        description: """
+            Experimental feature that allows targets to link to pages in their dependencies and that \
+            creates an additional "combined" DocC archive containing all the generated documentation.
+            """,
+        argumentTransformation: { $0 }
+    )
+    
+    static let enableCombinedDocumentationSupportFlagName = "enable-experimental-combined-documentation"
+}
+