Generate inputs from symbol graphs when there is no catalog

Author: d-ronnqvist

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

@@ -9,6 +9,7 @@
 */
 
 import Foundation
+import SymbolKit
 
 extension DocumentationContext {
 
@@ -160,11 +161,79 @@ extension DocumentationContext.InputsProvider {
     }
 }
 
+// MARK: Create without catalog
+
+extension DocumentationContext.InputsProvider {
+    /// Creates a collection of documentation inputs from the symbol graph files and other command line options.
+    ///
+    /// - Parameter options: Options to configure how the provider creates the documentation inputs.
+    /// - Returns: Inputs that categorize the files of the given catalog.
+    package func makeInputsFromSymbolGraphs(options: Options) throws -> DocumentationContext.Inputs? {
+        guard !options.additionalSymbolGraphFiles.isEmpty else {
+            return nil
+        }
+
+        // Find all the unique module names from the symbol graph files and generate a top level module page for each of them.
+        var moduleNames = Set<String>()
+        for url in options.additionalSymbolGraphFiles {
+            let data = try fileManager.contents(of: url)
+            let container = try JSONDecoder().decode(SymbolGraphModuleContainer.self, from: data)
+            moduleNames.insert(container.module.name)
+        }
+        let derivedDisplayName = moduleNames.count == 1 ? moduleNames.first : nil
+
+        let info = try DocumentationContext.Inputs.Info(bundleDiscoveryOptions: options, derivedDisplayName: derivedDisplayName)
+
+        var topLevelPages: [URL] = []
+        if moduleNames.count == 1, let moduleName = moduleNames.first, moduleName != info.displayName {
+            let tempURL = fileManager.uniqueTemporaryDirectory()
+            try? fileManager.createDirectory(at: tempURL, withIntermediateDirectories: true, attributes: nil)
+
+            let url = tempURL.appendingPathComponent("\(moduleName).md")
+            topLevelPages.append(url)
+            try fileManager.createFile(
+                at: url,
+                contents: Data("""
+                # ``\(moduleName)``
+                
+                @Metadata {
+                  @DisplayName("\(info.displayName)")
+                }
+                """.utf8),
+                options: .atomic
+            )
+        }
+
+        return DocumentationBundle(
+            info: info,
+            symbolGraphURLs: options.additionalSymbolGraphFiles,
+            markupURLs: topLevelPages,
+            miscResourceURLs: []
+        )
+    }
+}
+
+/// A wrapper type that decodes only the module in the symbol graph.
+private struct SymbolGraphModuleContainer: Decodable {
+    /// The decoded symbol graph module.
+    let module: SymbolGraph.Module
+
+    typealias CodingKeys = SymbolGraph.CodingKeys
+
+    public init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+
+        self.module = try container.decode(SymbolGraph.Module.self, forKey: .module)
+    }
+}
+
 // MARK: Discover and create
 
 extension DocumentationContext.InputsProvider {
     /// Traverses the file system from the given starting point to find a documentation catalog and creates a collection of documentation inputs from that catalog.
     ///
+    /// If the provider can't find a catalog, it will try to create documentation inputs from the option's symbol graph files.
+    ///
     /// - Parameters:
     ///   - startingPoint: The top of the directory hierarchy that the provider traverses to find a documentation catalog.
     ///   - allowArbitraryCatalogDirectories: Whether to treat the starting point as a documentation catalog if the provider doesn't find an actual catalog on the file system.
@@ -176,8 +245,10 @@ extension DocumentationContext.InputsProvider {
         allowArbitraryCatalogDirectories: Bool = false,
         options: Options
     ) throws -> DocumentationContext.Inputs? {
-        try findCatalog(startingPoint: startingPoint, allowArbitraryCatalogDirectories: allowArbitraryCatalogDirectories).map {
-            try makeInputs(contentOf: $0, options: options)
+        if let catalogURL = try findCatalog(startingPoint: startingPoint, allowArbitraryCatalogDirectories: allowArbitraryCatalogDirectories) {
+            try makeInputs(contentOf: catalogURL, options: options)
+        } else {
+            try makeInputsFromSymbolGraphs(options: options)
         }
     }
 }

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

@@ -190,4 +190,41 @@ class DocumentationInputsProviderTests: XCTestCase {
             )
         }
     }
+
+    func testGeneratesInputsFromSymbolGraphWhenThereIsNoCatalog() throws {
+        let fileSystem = try TestFileSystem(folders: [
+            Folder(name: "one", content: [
+                Folder(name: "two", content: [
+                    // Start search here.
+                    Folder(name: "three", content: [
+                        Folder(name: "four", content: []),
+                    ]),
+                ]),
+                // This catalog is outside the provider's search scope
+                Folder(name: "OutsideScope.docc", content: []),
+
+            ]),
+
+            Folder(name: "path", content: [
+                Folder(name: "to", content: [
+                    // The path to this symbol graph file is passed via the options
+                    JSONFile(name: "Something.symbols.json", content: makeSymbolGraph(moduleName: "Something")),
+                ])
+            ])
+        ])
+
+        let provider = DocumentationContext.InputsProvider(fileManager: fileSystem)
+        let startingPoint = URL(fileURLWithPath: "/one/two")
+
+        let foundBundle = try provider.inputs(
+            startingPoint: startingPoint,
+            options: .init(additionalSymbolGraphFiles: [
+                URL(fileURLWithPath: "/path/to/Something.symbols.json")])
+        )
+        XCTAssertEqual(foundBundle?.displayName, "Something")
+        XCTAssertEqual(foundBundle?.identifier, "Something")
+        XCTAssertEqual(foundBundle?.symbolGraphURLs.map(\.path), [
+            "/path/to/Something.symbols.json",
+        ])
+    }
 }