Add custom favicon (#1400)

Author: federicobucchi

Sources/SwiftDocC/Infrastructure/DocumentationBundle.swift

@@ -91,6 +91,10 @@ public struct DocumentationBundle {
 
     /// A custom JSON settings file used to theme renderer output.
     public let themeSettings: URL?
+
+    /// A custom favicon file to use for rendered output.
+    public let customFavicon: 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.
@@ -107,6 +111,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.
+    ///   - customFavicon: A custom favicon file to use for rendered output.
     public init(
         info: Info,
         baseURL: URL = URL(string: "/")!,
@@ -115,7 +120,8 @@ public struct DocumentationBundle {
         miscResourceURLs: [URL],
         customHeader: URL? = nil,
         customFooter: URL? = nil,
-        themeSettings: URL? = nil
+        themeSettings: URL? = nil,
+        customFavicon: URL? = nil
     ) {
         self.info = info
         self.baseURL = baseURL
@@ -125,6 +131,7 @@ public struct DocumentationBundle {
         self.customHeader = customHeader
         self.customFooter = customFooter
         self.themeSettings = themeSettings
+        self.customFavicon = customFavicon
         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,4 +84,12 @@ public enum DocumentationBundleFileTypes {
     public static func isThemeSettingsFile(_ url: URL) -> Bool {
         return url.lastPathComponent == themeSettingsFileName
     }
+
+    private static let customFaviconFileName = "favicon.ico"
+    /// Checks if a file is a custom favicon.
+    /// - Parameter url: The file to check.
+    /// - Returns: Whether or not the file at `url` is a custom favicon.
+    public static func isCustomFavicon(_ url: URL) -> Bool {
+        return url.lastPathComponent.lowercased() == customFaviconFileName
+    }
 }

Sources/SwiftDocC/Infrastructure/Input Discovery/DocumentationInputsProvider.swift

@@ -27,6 +27,7 @@ extension DocumentationContext {
     ///  ``DocumentationBundle/themeSettings``    | ``DocumentationBundleFileTypes/isThemeSettingsFile(_:)``
     ///  ``DocumentationBundle/customHeader``     | ``DocumentationBundleFileTypes/isCustomHeader(_:)``
     ///  ``DocumentationBundle/customFooter``     | ``DocumentationBundleFileTypes/isCustomFooter(_:)``
+    ///  ``DocumentationBundle/customFavicon``    | ``DocumentationBundleFileTypes/isCustomFavicon(_:)``
     ///  ``DocumentationBundle/miscResourceURLs`` | Any file not already matched above.
     ///
     /// ## Topics
@@ -165,7 +166,8 @@ extension DocumentationContext.InputsProvider {
             miscResourceURLs: foundContents.resources,
             customHeader:  shallowContent.first(where: FileTypes.isCustomHeader),
             customFooter:  shallowContent.first(where: FileTypes.isCustomFooter),
-            themeSettings: shallowContent.first(where: FileTypes.isThemeSettingsFile)
+            themeSettings: shallowContent.first(where: FileTypes.isThemeSettingsFile),
+            customFavicon: shallowContent.first(where: FileTypes.isCustomFavicon)
         )
     }
 

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

@@ -150,6 +150,16 @@ struct ConvertFileWritingConsumer: ConvertOutputConsumer, ExternalNodeConsumer {
             }
             try fileManager._copyItem(at: themeSettings, to: targetFile)
         }
+
+        // If a custom favicon is provided, it will be copied in the output directory
+        // The custom favicon will override the default one.
+        if let customFavicon = bundle.customFavicon {
+            let targetFile = targetFolder.appendingPathComponent(customFavicon.lastPathComponent, isDirectory: false)
+            if fileManager.fileExists(atPath: targetFile.path) {
+                try fileManager.removeItem(at: targetFile)
+            }
+            try fileManager._copyItem(at: customFavicon, to: targetFile)
+        }
     }
 
     func consume(linkableElementSummaries summaries: [LinkDestinationSummary]) throws {

Sources/docc/DocCDocumentation.docc/customizing-the-appearance-of-your-documentation-pages.md

@@ -166,6 +166,9 @@ follow in order to override an icon:
 > You can find all the possible identifier values for every valid icon kind in
 > the Open API [specification][1] for `theme-settings.json`.
 
+You can also specify a custom favicon for your documentation website by adding
+an optional `favicon.ico` file to the root of your documentation catalog.
+
 **Example**
 
 As a simple example, here is how you could update the icon used for articles in

Tests/SwiftDocCTests/Infrastructure/DocumentationBundleFileTypesTests.swift

@@ -55,4 +55,17 @@ class DocumentationBundleFileTypesTests: XCTestCase {
         XCTAssertFalse(DocumentationBundleFileTypes.isThemeSettingsFile(
             URL(fileURLWithPath: "/a/theme-settings.json/bar")))
     }
+
+    func testIsCustomFavicon() {
+        XCTAssertTrue(DocumentationBundleFileTypes.isCustomFavicon(
+            URL(fileURLWithPath: "favicon.ico")))
+        XCTAssertTrue(DocumentationBundleFileTypes.isCustomFavicon(
+            URL(fileURLWithPath: "/favicon.ico")))
+        XCTAssertTrue(DocumentationBundleFileTypes.isCustomFavicon(
+            URL(fileURLWithPath: "DocC.docc/favicon.ico")))
+        XCTAssertFalse(DocumentationBundleFileTypes.isCustomFavicon(
+            URL(fileURLWithPath: "favicon")))
+        XCTAssertFalse(DocumentationBundleFileTypes.isCustomFavicon(
+            URL(fileURLWithPath: "/favicon.ico/foo")))
+    }
 }

Tests/SwiftDocCTests/Infrastructure/Input Discovery/DocumentationInputsProviderTests.swift

@@ -28,9 +28,10 @@ class DocumentationInputsProviderTests: XCTestCase {
                         // This top-level Info.plist will be read for bundle information
                         InfoPlist(displayName: "CustomDisplayName"),
 
-                        // These top-level files will be treated as a custom footer and a custom theme
+                        // These top-level files will be treated as a custom footer, custom theme, and custom favicon
                         TextFile(name: "footer.html", utf8Content: ""),
                         TextFile(name: "theme-settings.json", utf8Content: ""),
+                        DataFile(name: "favicon.ico", data: Data()),
 
                         // Top-level content will be found
                         TextFile(name: "CCC.md", utf8Content: ""),
@@ -95,6 +96,7 @@ class DocumentationInputsProviderTests: XCTestCase {
                 "Found.docc/Inner/Info.plist",
                 "Found.docc/Inner/header.html",
                 "Found.docc/Inner/second.png",
+                "Found.docc/favicon.ico",
                 "Found.docc/first.png",
                 "Found.docc/footer.html",
                 "Found.docc/theme-settings.json",
@@ -107,6 +109,7 @@ class DocumentationInputsProviderTests: XCTestCase {
             XCTAssertEqual(bundle.customFooter.map(relativePathString), "Found.docc/footer.html")
             XCTAssertEqual(bundle.customHeader.map(relativePathString), nil)
             XCTAssertEqual(bundle.themeSettings.map(relativePathString), "Found.docc/theme-settings.json")
+            XCTAssertEqual(bundle.customFavicon.map(relativePathString), "Found.docc/favicon.ico")
         }
     }