Generate documentation content based on the symbol graph module names (#52)

rdar://84810134

Author: d-ronnqvist

Sources/SwiftDocC/Infrastructure/Workspace/GeneratedDataProvider.swift

@@ -9,47 +9,53 @@
 */
 
 import Foundation
+import SymbolKit
 
 /// A type that provides documentation bundles that it discovers by traversing the local file system.
 public struct GeneratedDataProvider: DocumentationWorkspaceDataProvider {
     public var identifier: String = UUID().uuidString
 
-    /// Options to configure how the provider generates documentation bundles.
-    public var options: BundleDiscoveryOptions
-    
-    private let info: DocumentationBundle.Info
-    private let topLevelPage: URL
     public typealias SymbolGraphDataLoader = (URL) -> Data?
     private let symbolGraphDataLoader: SymbolGraphDataLoader
 
-    /// Creates a new provider that recursively traverses the content of the given root URL to discover documentation bundles.
+    /// Creates a new provider that generates documentation bundles from the ``BundleDiscoveryOptions`` it is passed in ``bundles(options:)``.
     ///
     /// - Parameters:
-    ///   - options: Options to configure how the converter discovers documentation bundles.
     ///   - symbolGraphDataLoader: A closure that loads the raw data for a symbol graph file at a given URL.
-    public init(options: BundleDiscoveryOptions, symbolGraphDataLoader: @escaping SymbolGraphDataLoader) throws {
-        self.options = options
+    public init(symbolGraphDataLoader: @escaping SymbolGraphDataLoader) {
         self.symbolGraphDataLoader = symbolGraphDataLoader
+    }
+    
+    public func bundles(options: BundleDiscoveryOptions) throws -> [DocumentationBundle] {
+        let info: DocumentationBundle.Info
         do {
-            self.info = try DocumentationBundle.Info(bundleDiscoveryOptions: options)
+            info = try DocumentationBundle.Info(bundleDiscoveryOptions: options)
         } catch {
             throw Error.notEnoughDataToGenerateBundle(options: options, underlyingError: error)
         }
 
-        self.topLevelPage = URL(string: "\(info.displayName.replacingWhitespaceAndPunctuation(with: "-")).md")!
-    }
-    
-    public func bundles(options: BundleDiscoveryOptions) throws -> [DocumentationBundle] {
         guard !options.additionalSymbolGraphFiles.isEmpty else {
             return []
         }
 
+        // 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 {
+            guard let data = symbolGraphDataLoader(url) else {
+                throw Error.unableToLoadSymbolGraphData(url: url)
+            }
+            let container = try JSONDecoder().decode(SymbolGraphModuleContainer.self, from: data)
+            moduleNames.insert(container.module.name)
+        }
+        
+        let topLevelPages = moduleNames.map { URL(string: $0 + ".md")! }
+        
         return [
             DocumentationBundle(
                 info: info,
                 attributedCodeListings: [:],
                 symbolGraphURLs: options.additionalSymbolGraphFiles,
-                markupURLs: [topLevelPage],
+                markupURLs: topLevelPages,
                 miscResourceURLs: []
             )
         ]
@@ -92,10 +98,11 @@ public struct GeneratedDataProvider: DocumentationWorkspaceDataProvider {
     }
 
     public func contentsOfURL(_ url: URL) throws -> Data {
-        if url == topLevelPage {
-            let markdown = "# ``\(info.displayName)``"
+        if DocumentationBundleFileTypes.isMarkupFile(url) {
+            let moduleName = url.deletingPathExtension().lastPathComponent
+            let markdown = "# ``\(moduleName)``"
             return Data(markdown.utf8)
-        } else if options.additionalSymbolGraphFiles.contains(url) {
+        } else if DocumentationBundleFileTypes.isSymbolGraphFile(url) {
             guard let data = symbolGraphDataLoader(url) else {
                 throw Error.unableToLoadSymbolGraphData(url: url)
             }
@@ -105,3 +112,17 @@ public struct GeneratedDataProvider: DocumentationWorkspaceDataProvider {
         }
     }
 }
+
+/// 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)
+    }
+}

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

@@ -150,7 +150,7 @@ public struct ConvertAction: Action, RecreatingContext {
             dataProvider = try LocalFileSystemDataProvider(rootURL: rootURL)
         } else {
             self.context.externalMetadata.isGeneratedBundle = true
-            dataProvider = try GeneratedDataProvider(options: bundleDiscoveryOptions, symbolGraphDataLoader: { url in
+            dataProvider = GeneratedDataProvider(symbolGraphDataLoader: { url in
                 fileManager.contents(atPath: url.path)
             })
         }

Tests/SwiftDocCTests/Infrastructure/GeneratedDataProvider.swift

@@ -0,0 +1,87 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2021 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 XCTest
+@testable import SwiftDocC
+import SymbolKit
+
+class GeneratedDataProviderTests: XCTestCase {
+
+    func testGeneratingBundles() throws {
+        let firstSymbolGraph = SymbolGraph(
+            metadata: .init(
+                formatVersion: .init(major: 0, minor: 0, patch: 1),
+                generator: "unit-test"
+            ),
+            module: .init(
+                name: "FirstModuleName",
+                platform: .init()
+            ),
+            symbols: [],
+            relationships: []
+        )
+        var secondSymbolGraph = firstSymbolGraph
+        secondSymbolGraph.module.name = "SecondModuleName"
+        
+        let thirdSymbolGraph = firstSymbolGraph // Another symbol graph with the same module name
+        
+        let dataProvider = GeneratedDataProvider(
+            symbolGraphDataLoader: {
+                switch $0.lastPathComponent {
+                case "first.symbols.json":
+                    return try? JSONEncoder().encode(firstSymbolGraph)
+                case "second.symbols.json":
+                    return try? JSONEncoder().encode(secondSymbolGraph)
+                case "third.symbols.json":
+                    return try? JSONEncoder().encode(thirdSymbolGraph)
+                default:
+                    return nil
+                }
+            }
+        )
+        
+        let options = BundleDiscoveryOptions(
+            infoPlistFallbacks: [
+                "CFBundleDisplayName": "Custom Display Name",
+                "CFBundleIdentifier": "com.test.example",
+            ],
+            additionalSymbolGraphFiles: [
+                URL(fileURLWithPath: "first.symbols.json"),
+                URL(fileURLWithPath: "second.symbols.json"),
+                URL(fileURLWithPath: "third.symbols.json"),
+            ]
+        )
+        let bundles = try dataProvider.bundles(options: options)
+        XCTAssertEqual(bundles.count, 1)
+        let bundle = try XCTUnwrap(bundles.first)
+        
+        XCTAssertEqual(bundle.displayName, "Custom Display Name")
+        XCTAssertEqual(bundle.symbolGraphURLs.map { $0.lastPathComponent }.sorted(), [
+            "first.symbols.json",
+            "second.symbols.json",
+            "third.symbols.json",
+            
+        ])
+        XCTAssertEqual(bundle.markupURLs.map { $0.path }.sorted(), [
+            "FirstModuleName.md",
+            "SecondModuleName.md",
+            // No third file since that symbol graph has the same module name as the first
+        ])
+
+        XCTAssertEqual(
+            try String(data: dataProvider.contentsOfURL(URL(fileURLWithPath: "FirstModuleName.md")), encoding: .utf8),
+            "# ``FirstModuleName``"
+        )
+        XCTAssertEqual(
+            try String(data: dataProvider.contentsOfURL(URL(fileURLWithPath: "SecondModuleName.md")), encoding: .utf8),
+            "# ``SecondModuleName``"
+        )
+    }
+}

Tests/SwiftDocCUtilitiesTests/ConvertActionTests.swift

@@ -345,21 +345,22 @@ class ConvertActionTests: XCTestCase {
         var infoPlistFallbacks = [String: Any]()
         infoPlistFallbacks["CFBundleIdentifier"] = "com.example.test"
 
-        XCTAssertThrowsError(try ConvertAction(
-                documentationBundleURL: nil,
-                outOfProcessResolver: nil,
-                analyze: false,
-                targetDirectory: outputLocation.absoluteURL,
-                htmlTemplateDirectory: Folder.emptyHTMLTemplateDirectory.absoluteURL,
-                emitDigest: false,
-                currentPlatforms: nil,
-                fileManager: testDataProvider,
-                bundleDiscoveryOptions: BundleDiscoveryOptions(
-                    infoPlistFallbacks: infoPlistFallbacks,
-                    additionalSymbolGraphFiles: [URL(fileURLWithPath: "/Not-a-doc-bundle/MyKit.symbols.json")]
-                )
+        var action = try ConvertAction(
+            documentationBundleURL: nil,
+            outOfProcessResolver: nil,
+            analyze: false,
+            targetDirectory: outputLocation.absoluteURL,
+            htmlTemplateDirectory: Folder.emptyHTMLTemplateDirectory.absoluteURL,
+            emitDigest: false,
+            currentPlatforms: nil,
+            fileManager: testDataProvider,
+            bundleDiscoveryOptions: BundleDiscoveryOptions(
+                infoPlistFallbacks: infoPlistFallbacks,
+                additionalSymbolGraphFiles: [URL(fileURLWithPath: "/Not-a-doc-bundle/MyKit.symbols.json")]
             )
-        ) { error in
+        )
+        let logStorage = LogHandle.LogStorage()
+        XCTAssertThrowsError(try action.perform(logHandle: .memory(logStorage))) { error in
             XCTAssertEqual(error.localizedDescription, """
             The information provided as command line arguments is not enough to generate a documentation bundle: