Add support for custom scripts

Author: Lucca-mito

Sources/SwiftDocC/Infrastructure/DocumentationBundle.swift

@@ -110,11 +110,15 @@ public struct DocumentationBundle {
 
     /// A custom JSON settings file used to theme renderer output.
     public let themeSettings: URL?
+
     /// A URL prefix to be appended to the relative presentation URL.
     ///
     /// This is used when a built documentation is hosted in a known location.
     public let baseURL: URL
 
+    /// A custom JSON settings file used to add custom scripts to the renderer output.
+    public let customScripts: URL?
+    
     /// Creates a new collection of build inputs for a unit of documentation.
     ///
     /// - Parameters:
@@ -126,6 +130,7 @@ public struct DocumentationBundle {
     ///   - customHeader: A custom HTML file to use as the header for rendered output.
     ///   - customFooter: A custom HTML file to use as the footer for rendered output.
     ///   - themeSettings: A custom JSON settings file used to theme renderer output.
+    ///   - customScripts: A custom JSON settings file used to add custom scripts to the renderer output.
     public init(
         info: Info,
         baseURL: URL = URL(string: "/")!,
@@ -134,7 +139,8 @@ public struct DocumentationBundle {
         miscResourceURLs: [URL],
         customHeader: URL? = nil,
         customFooter: URL? = nil,
-        themeSettings: URL? = nil
+        themeSettings: URL? = nil,
+        customScripts: URL? = nil
     ) {
         self.info = info
         self.baseURL = baseURL
@@ -144,6 +150,7 @@ public struct DocumentationBundle {
         self.customHeader = customHeader
         self.customFooter = customFooter
         self.themeSettings = themeSettings
+        self.customScripts = customScripts
         self.rootReference = ResolvedTopicReference(bundleID: info.id, path: "/", sourceLanguage: .swift)
         self.documentationRootReference = ResolvedTopicReference(bundleID: info.id, path: NodeURLGenerator.Path.documentationFolder, sourceLanguage: .swift)
         self.tutorialTableOfContentsContainer = ResolvedTopicReference(bundleID: info.id, path: NodeURLGenerator.Path.tutorialsFolder, sourceLanguage: .swift)

Sources/SwiftDocC/Infrastructure/DocumentationBundleFileTypes.swift

@@ -84,6 +84,14 @@ public enum DocumentationBundleFileTypes {
     public static func isThemeSettingsFile(_ url: URL) -> Bool {
         return url.lastPathComponent == themeSettingsFileName
     }
+    
+    private static let customScriptsFileName = "custom-scripts.json"
+    /// Checks if a file is `custom-scripts.json`.
+    /// - Parameter url: The file to check.
+    /// - Returns: Whether or not the file at `url` is `custom-scripts.json`.
+    public static func isCustomScriptsFile(_ url: URL) -> Bool {
+        return url.lastPathComponent == customScriptsFileName
+    }
 }
 
 extension DocumentationBundleFileTypes {

Sources/SwiftDocC/Infrastructure/DocumentationContext.swift

@@ -1784,6 +1784,7 @@ public class DocumentationContext {
 
     private static let supportedImageExtensions: Set<String> = ["png", "jpg", "jpeg", "svg", "gif"]
     private static let supportedVideoExtensions: Set<String> = ["mov", "mp4"]
+    private static let supportedScriptExtensions: Set<String> = ["js"]
 
     // TODO: Move this functionality to ``DocumentationBundleFileTypes`` (rdar://68156425).
 
@@ -1878,6 +1879,14 @@ public class DocumentationContext {
     public func registeredDownloadsAssets(forBundleID bundleIdentifier: BundleIdentifier) -> [DataAsset] {
         registeredDownloadsAssets(for: DocumentationBundle.Identifier(rawValue: bundleIdentifier))
     }
+    
+    /// Returns a list of all the custom scripts that registered for a given `bundleIdentifier`.
+    ///
+    /// - Parameter bundleIdentifier: The identifier of the bundle to return download assets for.
+    /// - Returns: A list of all the custom scripts for the given bundle.
+    public func registeredCustomScripts(forBundleID bundleIdentifier: BundleIdentifier) -> [DataAsset] {
+        return registeredAssets(withExtensions: DocumentationContext.supportedScriptExtensions, forBundleID: bundleIdentifier)
+    }
 
     typealias Articles = [DocumentationContext.SemanticResult<Article>]
     private typealias ArticlesTuple = (articles: Articles, rootPageArticles: Articles)

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

@@ -83,6 +83,7 @@ extension LocalFileSystemDataProvider: DocumentationWorkspaceDataProvider {
         let customHeader = findCustomHeader(bundleChildren)?.url
         let customFooter = findCustomFooter(bundleChildren)?.url
         let themeSettings = findThemeSettings(bundleChildren)?.url
+        let customScripts = findCustomScripts(bundleChildren)?.url
 
         return DocumentationBundle(
             info: info,
@@ -91,7 +92,8 @@ extension LocalFileSystemDataProvider: DocumentationWorkspaceDataProvider {
             miscResourceURLs: miscResources,
             customHeader: customHeader,
             customFooter: customFooter,
-            themeSettings: themeSettings
+            themeSettings: themeSettings,
+            customScripts: customScripts
         )
     }
 
@@ -140,6 +142,10 @@ extension LocalFileSystemDataProvider: DocumentationWorkspaceDataProvider {
     private func findThemeSettings(_ bundleChildren: [FSNode]) -> FSNode.File? {
         return bundleChildren.firstFile { DocumentationBundleFileTypes.isThemeSettingsFile($0.url) }
     }
+    
+    private func findCustomScripts(_ bundleChildren: [FSNode]) -> FSNode.File? {
+        return bundleChildren.firstFile { DocumentationBundleFileTypes.isCustomScriptsFile($0.url) }
+    }
 }
 
 @available(*, deprecated, message: "This deprecated API will be removed after 6.2 is released.")

Sources/SwiftDocC/SwiftDocC.docc/Resources/CustomScripts.spec.json

@@ -0,0 +1,98 @@
+{
+    "openapi": "3.0.0",
+    "info": {
+        "title": "Custom Scripts",
+        "description": "This spec describes the permissible contents of a custom-scripts.json file in a documentation catalog, which is used to add custom scripts to a DocC-generated website.",
+        "version": "0.0.1"
+    },
+    "paths": {},
+    "components": {
+        "schemas": {
+            "Scripts": {
+                "type": "array",
+                "description": "An array of custom scripts, which is the top-level container in a custom-scripts.json file.",
+                "items": {
+                    "oneOf": [
+                        { "$ref": "#/components/schemas/ExternalScript" },
+                        { "$ref": "#/components/schemas/LocalScript" },
+                        { "$ref": "#/components/schemas/InlineScript" }
+                    ]
+                }
+            },
+            "Script": {
+                "type": "object",
+                "description": "An abstract schema representing any script, from which all three script types inherit.",
+                "properties": {
+                    "type": {
+                        "type": "string",
+                        "description": "The `type` attribute of the HTML script element."
+                    },
+                    "run": {
+                        "type": "string",
+                        "enum": ["on-load", "on-navigate", "on-load-and-navigate"],
+                        "description": "Whether the custom script should be run only on the initial page load, each time the reader navigates after the initial page load, or both."
+                    }
+                }
+            },
+            "ScriptFromFile": {
+                "description": "An abstract schema representing a script from an external or local file; that is, not an inline script.",
+                "allOf": [
+                    { "$ref": "#/components/schemas/Script" },
+                    {
+                        "properties": {
+                            "async": { "type": "boolean" },
+                            "defer": { "type": "boolean" },
+                            "integrity": { "type": "string" },
+                        }
+                    }
+                ]
+            },
+            "ExternalScript": {
+                "description": "A script at an external URL.",
+                "allOf": [
+                    { "$ref": "#/components/schemas/ScriptFromFile" },
+                    {
+                        "required": ["url"],
+                        "properties": {
+                            "url": { "type": "string" }
+                        }
+                    }
+                ]
+            },
+            "LocalScript": {
+                "description": "A script from a local file.",
+                "allOf": [
+                    { "$ref": "#/components/schemas/ScriptFromFile" },
+                    {
+                        "required": ["name"],
+                        "properties": {
+                            "name": {
+                                "type": "string",
+                                "description": "The name of the local script file, optionally including the '.js' extension."
+                            },
+                        }
+                    }
+                ]
+            },
+            "InlineScript": {
+                "description": "A script whose source code is in the custom-scripts.json file itself.",
+                "allOf": [
+                    { "$ref": "#/components/schemas/Script" },
+                    {
+                        "required": ["code"],
+                        "properties": {
+                            "code": {
+                                "type": "string",
+                                "description": "The source code of the inline script."
+                            }
+                        }
+                    }
+                ]
+            }
+        },
+        "requestBodies": {},
+        "securitySchemes": {},
+        "links": {},
+        "callbacks": {}
+    }
+}

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

@@ -120,6 +120,18 @@ struct ConvertFileWritingConsumer: ConvertOutputConsumer {
         for downloadAsset in context.registeredDownloadsAssets(for: bundleID) {
             try copyAsset(downloadAsset, to: downloadsDirectory)
         }
+        
+        // Create custom scripts directory if needed. Do not append the bundle identifier.
+        let scriptsDirectory = targetFolder
+            .appendingPathComponent("custom-scripts", isDirectory: true)
+        if !fileManager.directoryExists(atPath: scriptsDirectory.path) {
+            try fileManager.createDirectory(at: scriptsDirectory, withIntermediateDirectories: true, attributes: nil)
+        }
+        
+        // Copy all registered custom scripts to the output directory.
+        for customScript in context.registeredCustomScripts(forBundleID: bundleIdentifier) {
+            try copyAsset(customScript, to: scriptsDirectory)
+        }
 
         // If the bundle contains a `header.html` file, inject a <template> into
         // the `index.html` file using its contents. This will only be done if
@@ -145,6 +157,16 @@ struct ConvertFileWritingConsumer: ConvertOutputConsumer {
             }
             try fileManager.copyItem(at: themeSettings, to: targetFile)
         }
+        
+        // Copy the `custom-scripts.json` file into the output directory if one
+        // is provided.
+        if let customScripts = bundle.customScripts {
+            let targetFile = targetFolder.appendingPathComponent(customScripts.lastPathComponent, isDirectory: false)
+            if fileManager.fileExists(atPath: targetFile.path) {
+                try fileManager.removeItem(at: targetFile)
+            }
+            try fileManager.copyItem(at: customScripts, to: targetFile)
+        }
     }
 
     func consume(linkableElementSummaries summaries: [LinkDestinationSummary]) throws {

Sources/SwiftDocCUtilities/PreviewServer/RequestHandler/FileRequestHandler.swift

@@ -107,6 +107,7 @@ struct FileRequestHandler: RequestHandlerFactory {
         TopLevelAssetFileMetadata(filePath: "/favicon.ico", mimetype: "image/x-icon"),
         TopLevelAssetFileMetadata(filePath: "/theme-settings.js", mimetype: "text/javascript"),
         TopLevelAssetFileMetadata(filePath: "/theme-settings.json", mimetype: "application/json"),
+        TopLevelAssetFileMetadata(filePath: "/custom-scripts.json", mimetype: "application/json"),
     ]
 
     /// Returns a Boolean value that indicates whether the given path is located inside an asset folder.

Tests/SwiftDocCTests/Infrastructure/DocumentationBundleFileTypesTests.swift

@@ -13,46 +13,49 @@ import XCTest
 
 class DocumentationBundleFileTypesTests: XCTestCase {
     func testIsCustomHeader() {
-        XCTAssertTrue(DocumentationBundleFileTypes.isCustomHeader(
-            URL(fileURLWithPath: "header.html")))
-        XCTAssertTrue(DocumentationBundleFileTypes.isCustomHeader(
-            URL(fileURLWithPath: "/header.html")))
-        XCTAssertFalse(DocumentationBundleFileTypes.isCustomHeader(
-            URL(fileURLWithPath: "header")))
-        XCTAssertFalse(DocumentationBundleFileTypes.isCustomHeader(
-            URL(fileURLWithPath: "/header.html/foo")))
-        XCTAssertFalse(DocumentationBundleFileTypes.isCustomHeader(
-            URL(fileURLWithPath: "footer.html")))
-        XCTAssertTrue(DocumentationBundleFileTypes.isCustomHeader(
-            URL(fileURLWithPath: "DocC.docc/header.html")))
+        test(whether: DocumentationBundleFileTypes.isCustomHeader, matchesFilesNamed: "header", withExtension: "html")
     }
 
     func testIsCustomFooter() {
-        XCTAssertTrue(DocumentationBundleFileTypes.isCustomFooter(
-            URL(fileURLWithPath: "footer.html")))
-        XCTAssertTrue(DocumentationBundleFileTypes.isCustomFooter(
-            URL(fileURLWithPath: "/footer.html")))
-        XCTAssertFalse(DocumentationBundleFileTypes.isCustomFooter(
-            URL(fileURLWithPath: "footer")))
-        XCTAssertFalse(DocumentationBundleFileTypes.isCustomFooter(
-            URL(fileURLWithPath: "/footer.html/foo")))
-        XCTAssertFalse(DocumentationBundleFileTypes.isCustomFooter(
-            URL(fileURLWithPath: "header.html")))
-        XCTAssertTrue(DocumentationBundleFileTypes.isCustomFooter(
-            URL(fileURLWithPath: "DocC.docc/footer.html")))
+        test(whether: DocumentationBundleFileTypes.isCustomFooter, matchesFilesNamed: "footer", withExtension: "html")
     }
 
     func testIsThemeSettingsFile() {
-        XCTAssertTrue(DocumentationBundleFileTypes.isThemeSettingsFile(
-            URL(fileURLWithPath: "theme-settings.json")))
-        XCTAssertTrue(DocumentationBundleFileTypes.isThemeSettingsFile(
-            URL(fileURLWithPath: "/a/b/theme-settings.json")))
-
-        XCTAssertFalse(DocumentationBundleFileTypes.isThemeSettingsFile(
-            URL(fileURLWithPath: "theme-settings.txt")))
-        XCTAssertFalse(DocumentationBundleFileTypes.isThemeSettingsFile(
-            URL(fileURLWithPath: "not-theme-settings.json")))
-        XCTAssertFalse(DocumentationBundleFileTypes.isThemeSettingsFile(
-            URL(fileURLWithPath: "/a/theme-settings.json/bar")))
+        test(whether: DocumentationBundleFileTypes.isThemeSettingsFile, matchesFilesNamed: "theme-settings", withExtension: "json")
+    }
+    
+    func testIsCustomScriptsFile() {
+        test(whether: DocumentationBundleFileTypes.isCustomScriptsFile, matchesFilesNamed: "custom-scripts", withExtension: "json")
+    }
+    
+    private func test(
+        whether predicate: (URL) -> Bool,
+        matchesFilesNamed fileName: String,
+        withExtension extension: String
+    ) {
+        let fileNameWithExtension = "\(fileName).\(`extension`)"
+        
+        let pathsThatShouldMatch = [
+            fileNameWithExtension,
+            "/\(fileNameWithExtension)",
+            "DocC/docc/\(fileNameWithExtension)",
+            "/a/b/\(fileNameWithExtension)"
+        ].map { URL(fileURLWithPath: $0) }
+        
+        let pathsThatShouldNotMatch = [
+            fileName,
+            "/\(fileNameWithExtension)/foo",
+            "/a/\(fileNameWithExtension)/bar",
+            "\(fileName).wrongextension",
+            "wrongname.\(`extension`)"
+        ].map { URL(fileURLWithPath: $0) }
+        
+        for url in pathsThatShouldMatch {
+            XCTAssertTrue(predicate(url))
+        }
+        
+        for url in pathsThatShouldNotMatch {
+            XCTAssertFalse(predicate(url))
+        }
     }
 }

Tests/SwiftDocCUtilitiesTests/ConvertActionStaticHostableTests.swift

@@ -47,7 +47,7 @@ class ConvertActionStaticHostableTests: StaticHostingBaseTests {
         _ = try await action.perform(logHandle: .none)
 
         // Test the content of the output folder.
-        var expectedContent = ["data", "documentation", "tutorials", "downloads", "images", "metadata.json" ,"videos", "index.html", "index"]
+        var expectedContent = ["data", "documentation", "tutorials", "downloads", "images", "custom-scripts", "metadata.json", "videos", "index.html", "index"]
         expectedContent += templateFolder.content.filter { $0 is Folder }.map{ $0.name }
 
         let output = try fileManager.contentsOfDirectory(atPath: targetBundleURL.path)

Tests/SwiftDocCUtilitiesTests/ConvertActionTests.swift

@@ -3108,6 +3108,7 @@ class ConvertActionTests: XCTestCase {
 
         XCTAssertEqual(fileSystem.dump(subHierarchyFrom: targetURL.path), """
         Output.doccarchive/
+        ├─ custom-scripts/
         ├─ data/
         │  ╰─ documentation/
         │     ╰─ something.json