Merge branch 'main' into main

Author: Anthony-Eid

Sources/SwiftDocC/Infrastructure/Bundle Assets/DataAssetManager.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-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
@@ -12,17 +12,6 @@ import Foundation
 
 /// A container for a collection of data. Each data can have multiple variants.
 struct DataAssetManager {
-    enum Error: DescribedError {
-        case invalidImageAsset(URL)
-        
-        var errorDescription: String {
-            switch self {
-                case .invalidImageAsset(let url):
-                    return "The dimensions of the image at \(url.path.singleQuoted) could not be computed because the file is not a valid image."
-            }
-        }
-    }
-    
     var storage = [String: DataAsset]()
 
     // A "file name with no extension" to "file name with extension" index
@@ -113,12 +102,10 @@ struct DataAssetManager {
         return (reference: dataReference, traits: traitCollection, metadata: metadata)
     }
 
-    /**
-     Registers a collection of data and determines their trait collection.
-
-     Data objects which have a file name ending with '~dark' are associated to their light variant.
-     - Throws: Will throw `Error.invalidImageAsset(URL)` if fails to read the size of an image asset (e.g. the file is corrupt).
-     */
+    
+    /// Registers a collection of data and determines their trait collection.
+    ///
+    /// Data objects which have a file name ending with '~dark' are associated to their light variant.
     mutating func register<Datas: Collection>(data datas: Datas, dataProvider: DocumentationContextDataProvider? = nil, bundle documentationBundle: DocumentationBundle? = nil) throws where Datas.Element == URL {
         for dataURL in datas {
             let meta = try referenceMetaInformationForDataURL(dataURL, dataProvider: dataProvider, bundle: documentationBundle)

Sources/SwiftDocC/Infrastructure/Link Resolution/BidirectionalTree.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021-2022 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-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
@@ -176,21 +176,3 @@ fileprivate extension Array where Element == FSNode {
         return matches
     }
 }
-
-/// An issue discovering a bundle in a workspace.
-enum WorkspaceError: DescribedError {
-    /// The bundle was missing an Info.plist file.
-    case missingInfoPlist(url: URL)
-    /// The root element of the Info.plist file was an array rather than a dictionary.
-    case notADictionaryAtRoot(url: URL)
-    
-    /// A plain-text representation of the error.
-    var errorDescription: String {
-        switch self {
-        case .missingInfoPlist(let url):
-            return "A bundle was found in the workspace at '\(url)' but it was missing an Info.plist."
-        case .notADictionaryAtRoot(let url):
-            return "A bundle was found in the workspace but its Info.plist at '\(url)' was not structured correctly: it contained a root array rather than a root dictionary."
-        }
-    }
-}

Sources/SwiftDocC/Infrastructure/Workspace/LocalFileSystemDataProvider+BundleDiscovery.swift

@@ -493,7 +493,11 @@ public struct RenderNodeTranslator: SemanticVisitor {
     }
 
     public mutating func visitVideoMedia(_ videoMedia: VideoMedia) -> RenderTree? {
-        return createAndRegisterRenderReference(forMedia: videoMedia.source, poster: videoMedia.poster)
+        return createAndRegisterRenderReference(
+            forMedia: videoMedia.source,
+            poster: videoMedia.poster,
+            altText: videoMedia.altText
+        )
     }
 
     public mutating func visitChapter(_ chapter: Chapter) -> RenderTree? {

Sources/SwiftDocC/Model/Rendering/RenderNodeTranslator.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-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
@@ -43,11 +43,9 @@ public struct RenderNodeVariantOverridesApplier {
         var variantOverrides: VariantOverrides?
     }
 
-    /// An error that occured while applying overrides in a render node.
+    @available(*, deprecated, message: "This error is never raised. This deprecated API will be removed after 5.11 is released")
     public enum Error: DescribedError {
-        /// An error indicating that the error node is corrupted or malformed.
         case corruptedRenderNode
-        
         public var errorDescription: String {
             switch self {
             case .corruptedRenderNode:

Sources/SwiftDocC/Model/Rendering/Variants/RenderNodeVariantOverridesApplier.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-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
@@ -15,18 +15,6 @@ import SwiftDocC
 ///
 /// The render node writer writes the JSON files into a hierarchy of folders and subfolders based on the relative URL for each node.
 class JSONEncodingRenderNodeWriter {
-    /// Errors that may occur while writing render node JSON files.
-    enum Error: DescribedError {
-        /// A file already exist at this path.
-        case fileExists(String)
-        /// The absolute path to the file is too long.
-        public var errorDescription: String {
-            switch self {
-            case .fileExists(let path): return "File already exists at: '\(path)'"
-            }
-        }
-    }
-    
     private let renderNodeURLGenerator: NodeURLGenerator
     private let targetFolder: URL
     private let transformForStaticHostingIndexHTML: URL?
@@ -56,7 +44,6 @@ class JSONEncodingRenderNodeWriter {
     /// create those intermediate folders before writing the JSON file.
     ///
     /// - Parameter renderNode: The node which the writer object writes to a JSON file.
-    /// - Throws: A ``Error/fileExists`` error if a file already exists at the location for this node's JSON file.
     func write(_ renderNode: RenderNode) throws {
         let fileSafePath = NodeURLGenerator.fileSafeReferencePath(
             renderNode.identifier,

Sources/SwiftDocCUtilities/Action/Actions/Convert/JSONEncodingRenderNodeWriter.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021-2023 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-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
@@ -13,16 +13,6 @@ import SwiftDocC
 
 /// An action that creates an index of a documentation bundle.
 public struct IndexAction: Action {
-    enum Error: DescribedError {
-        case doesNotContainBundle(url: URL)
-        var errorDescription: String {
-            switch self {
-            case .doesNotContainBundle(let url):
-                return "The directory at '\(url)' and its subdirectories do not contain at least one valid documentation bundle. A documentation bundle is a directory ending in `.docc`."
-            }
-        }
-    }
-
     let rootURL: URL
     let outputURL: URL
     let bundleIdentifier: String

Sources/SwiftDocCUtilities/Action/Actions/IndexAction.swift

@@ -0,0 +1,31 @@
+/*
+ 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
+*/
+
+import Foundation
+import SwiftDocC
+
+struct CatalogTemplate {
+    
+    let files: [String: String]
+    let additionalDirectories: [String]
+    
+    /// Creates a Catalog Template using one of the provided template kinds.
+    init(_ templateKind: CatalogTemplateKind, title: String) throws {
+        switch templateKind {
+        case .articleOnly:
+            self.files = CatalogTemplateKind.articleOnlyTemplateFiles(title)
+            self.additionalDirectories = ["Resources"]
+        case .tutorial:
+            self.files = CatalogTemplateKind.tutorialTemplateFiles(title)
+            self.additionalDirectories = ["Resources", "Chapter01/Resources"]
+            
+        }
+    }
+}