Add external media support in documentation

Sources/SwiftDocC/Infrastructure/DocumentationContext.swift

@@ -2622,14 +2622,21 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
             return localAsset
         }
 
-        if let externallyResolvedAsset = fallbackAssetResolvers[bundleIdentifier].flatMap({
-            $0.resolve(assetNamed: name, bundleIdentifier: bundleIdentifier)
-        }) {
-            assetManagers[bundleIdentifier, default: DataAssetManager()].register(
-                dataAsset: externallyResolvedAsset, forName: name)
+        if let fallbackAssetResolver = fallbackAssetResolvers[bundleIdentifier],
+           let externallyResolvedAsset = fallbackAssetResolver.resolve(assetNamed: name, bundleIdentifier: bundleIdentifier) {
+            assetManagers[bundleIdentifier, default: DataAssetManager()]
+                .register(dataAsset: externallyResolvedAsset, forName: name)
             return externallyResolvedAsset
         }
 
+        // If no fallbackAssetResolver is set, try to treat it as external media link
+        if let externalMediaLink = URL(string: name),
+           externalMediaLink.isAbsoluteWebURL {
+            var asset = DataAsset()
+            asset.context = .display
+            asset.register(externalMediaLink, with: DataTraitCollection(userInterfaceStyle: .light, displayScale: .standard))
+            return asset
+        }
         return nil
     }
 

Sources/SwiftDocC/Model/Rendering/References/ImageReference.swift

@@ -74,9 +74,7 @@ public struct ImageReference: MediaReference, URLReference {
         var result = [VariantProxy]()
         // sort assets by URL path for deterministic sorting of images
         asset.variants.sorted(by: \.value.path).forEach { (key, value) in
-            // If a scheme is present it means it's an absolute URL
-            let isAbsoluteWebURL = !value.isFileURL && value.scheme?.isEmpty == false
-            let url = isAbsoluteWebURL ? value : destinationURL(for: value.lastPathComponent)
+            let url = value.isAbsoluteWebURL ? value : destinationURL(for: value.lastPathComponent)
             result.append(VariantProxy(url: url, traits: key))
         }
         try container.encode(result, forKey: .variants)

Sources/SwiftDocC/Model/Rendering/References/VideoReference.swift

@@ -81,9 +81,7 @@ public struct VideoReference: MediaReference, URLReference {
         // convert the data asset to a serializable object
         var result = [VariantProxy]()
         asset.variants.sorted(by: \.value.path).forEach { (key, value) in
-            // If a scheme is present it means it's an absolute URL
-            let isAbsoluteWebURL = !value.isFileURL && value.scheme?.isEmpty == false
-            let url = isAbsoluteWebURL ? value : destinationURL(for: value.lastPathComponent)
+            let url = value.isAbsoluteWebURL ? value : destinationURL(for: value.lastPathComponent)
             result.append(VariantProxy(url: url, traits: key))
         }
         try container.encode(result, forKey: .variants)

Sources/SwiftDocC/Model/Rendering/Tutorial/References/DownloadReference.swift

@@ -62,7 +62,6 @@ public struct DownloadReference: RenderReference, URLReference {
 
 extension DownloadReference {
     private func renderURL(for url: URL) -> URL {
-        let isAbsoluteWebURL = !url.isFileURL && url.scheme?.isEmpty == false && url.scheme != ResolvedTopicReference.urlScheme // if scheme is present it means it's an absolute URL
-        return isAbsoluteWebURL ? url : destinationURL(for: url.lastPathComponent)
+        url.isAbsoluteWebURL ? url : destinationURL(for: url.lastPathComponent)
     }
 }

Sources/SwiftDocC/Utility/FoundationExtensions/URL+IsAbsoluteWebURL.swift

@@ -0,0 +1,26 @@
+/*
+ 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
+*/
+
+import Foundation
+
+extension URL {
+    /// Returns true if the scheme is not `nil` , not `file:`, not `ResolvedTopicReference.urlScheme`.
+    ///
+    /// - Returns: A Boolean value indicating whether the url is an absolute web URL.
+    var isAbsoluteWebURL: Bool {
+        guard !isFileURL,
+              let scheme = scheme ,
+              !scheme.isEmpty,
+              scheme != ResolvedTopicReference.urlScheme else {
+            return false
+        }
+        return true
+    }
+}

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

@@ -55,7 +55,7 @@ struct ConvertFileWritingConsumer: ConvertOutputConsumer {
 
     func consume(assetsInBundle bundle: DocumentationBundle) throws {
         func copyAsset(_ asset: DataAsset, to destinationFolder: URL) throws {
-            for sourceURL in asset.variants.values {
+            for sourceURL in asset.variants.values where !sourceURL.isAbsoluteWebURL  {
                 let assetName = sourceURL.lastPathComponent
                 try fileManager.copyItem(
                     at: sourceURL,

Sources/SwiftDocCUtilities/Utility/FoundationExtensions/URL+IsAbsoluteWebURL.swift

@@ -0,0 +1,25 @@
+/*
+ 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
+*/
+
+import Foundation
+
+extension URL {
+    /// Returns true if the scheme is not `nil` , not `file:`.
+    ///
+    /// - Returns: A Boolean value indicating whether the url is an absolute web URL.
+    var isAbsoluteWebURL: Bool {
+        guard !isFileURL,
+              let scheme = scheme ,
+              !scheme.isEmpty else {
+            return false
+        }
+        return true
+    }
+}

Tests/SwiftDocCTests/Infrastructure/DocumentationContextTests.swift

@@ -510,6 +510,26 @@ class DocumentationContextTests: XCTestCase {
         )
     }
 
+    func testExternalAssets() throws {
+        let workspace = DocumentationWorkspace()
+        let context = try DocumentationContext(dataProvider: workspace)
+        let bundle = try testBundle(named: "TestBundle")
+
+        let image = context.resolveAsset(named: "https://example.com/figure.png", in: bundle.rootReference)
+        XCTAssertNotNil(image)
+        guard let image = image else {
+            return
+        }
+        XCTAssertEqual(image.context, .display)
+        XCTAssertEqual(image.variants, [DataTraitCollection(userInterfaceStyle: .light, displayScale: .standard): URL(string: "https://example.com/figure.png")!])
+
+        let video = context.resolveAsset(named: "https://example.com/introvideo.mp4", in: bundle.rootReference)
+        XCTAssertNotNil(video)
+        guard let video = video else { return }
+        XCTAssertEqual(video.context, .display)
+        XCTAssertEqual(video.variants, [DataTraitCollection(userInterfaceStyle: .light, displayScale: .standard): URL(string: "https://example.com/introvideo.mp4")!])
+    }
+
     func testDownloadAssets() throws {
         let workspace = DocumentationWorkspace()
         let context = try DocumentationContext(dataProvider: workspace)

Tests/SwiftDocCTests/Utility/URL+IsAbsoluteWebURLTests.swift

@@ -0,0 +1,26 @@
+/*
+ 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
+*/
+
+@testable import SwiftDocC
+import XCTest
+
+class URL_IsAbsoluteWebURLTests: XCTestCase {
+    func testisAbsoluteWebURL() throws {
+        let localURL = URL(fileURLWithPath: "/Users/username/Documents/Some Folder/Some Document.txt")
+        let topReferenceURL = try XCTUnwrap(URL(string: "doc://swift-doc"))
+        let webURL = try XCTUnwrap(URL(string: "swift.org"))
+        let absoluteWebURL = try XCTUnwrap(URL(string: "https://swift.org"))
+
+        XCTAssertEqual(localURL.isAbsoluteWebURL, false)
+        XCTAssertEqual(topReferenceURL.isAbsoluteWebURL, false)
+        XCTAssertEqual(webURL.isAbsoluteWebURL, false)
+        XCTAssertEqual(absoluteWebURL.isAbsoluteWebURL, true)
+    }
+}

Tests/SwiftDocCUtilitiesTests/Utility/URL+IsAbsoluteWebURLTests.swift

@@ -0,0 +1,26 @@
+/*
+ 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
+*/
+
+@testable import SwiftDocCUtilities
+import XCTest
+
+class URL_IsAbsoluteWebURLTests: XCTestCase {
+    func testisAbsoluteWebURL() throws {
+        let localURL = URL(fileURLWithPath: "/Users/username/Documents/Some Folder/Some Document.txt")
+        let topReferenceURL = try XCTUnwrap(URL(string: "doc://swift-doc"))
+        let webURL = try XCTUnwrap(URL(string: "swift.org"))
+        let absoluteWebURL = try XCTUnwrap(URL(string: "https://swift.org"))
+
+        XCTAssertEqual(localURL.isAbsoluteWebURL, false)
+        XCTAssertEqual(topReferenceURL.isAbsoluteWebURL, true)
+        XCTAssertEqual(webURL.isAbsoluteWebURL, false)
+        XCTAssertEqual(absoluteWebURL.isAbsoluteWebURL, true)
+    }
+}