1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
|
/*
This source file is part of the Swift.org open source project
Copyright (c) 2021-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
import SymbolKit
/// A type that provides documentation bundles that it discovers by traversing the local file system.
public class GeneratedDataProvider: DocumentationWorkspaceDataProvider {
public var identifier: String = UUID().uuidString
public typealias SymbolGraphDataLoader = (URL) -> Data?
private let symbolGraphDataLoader: SymbolGraphDataLoader
private var generatedMarkdownFiles: [String: Data] = [:]
/// Creates a new provider that generates documentation bundles from the ``BundleDiscoveryOptions`` it is passed in ``bundles(options:)``.
///
/// - Parameters:
/// - symbolGraphDataLoader: A closure that loads the raw data for a symbol graph file at a given URL.
public init(symbolGraphDataLoader: @escaping SymbolGraphDataLoader) {
self.symbolGraphDataLoader = symbolGraphDataLoader
}
public func bundles(options: BundleDiscoveryOptions) throws -> [DocumentationBundle] {
// 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 info: DocumentationBundle.Info
do {
let derivedDisplayName: String?
if moduleNames.count == 1, let moduleName = moduleNames.first {
derivedDisplayName = moduleName
} else {
derivedDisplayName = nil
}
info = try DocumentationBundle.Info(
bundleDiscoveryOptions: options,
derivedDisplayName: derivedDisplayName
)
} catch {
throw Error.notEnoughDataToGenerateBundle(options: options, underlyingError: error)
}
guard !options.additionalSymbolGraphFiles.isEmpty else {
return []
}
if moduleNames.count == 1, let moduleName = moduleNames.first, moduleName != info.displayName {
generatedMarkdownFiles[moduleName] = Data("""
# ``\(moduleName)``
@Metadata {
@DisplayName("\(info.displayName)")
}
""".utf8)
} else {
for moduleName in moduleNames {
generatedMarkdownFiles[moduleName] = Data("# ``\(moduleName)``".utf8)
}
}
let topLevelPages = generatedMarkdownFiles.keys.map { URL(string: $0 + ".md")! }
return [
DocumentationBundle(
info: info,
attributedCodeListings: [:],
symbolGraphURLs: options.additionalSymbolGraphFiles,
markupURLs: topLevelPages,
miscResourceURLs: []
)
]
}
enum Error: DescribedError {
case unableToLoadSymbolGraphData(url: URL)
case notEnoughDataToGenerateBundle(options: BundleDiscoveryOptions, underlyingError: Swift.Error?)
var errorDescription: String {
switch self {
case .unableToLoadSymbolGraphData(let url):
return "Unable to load data for symbol graph file at \(url.path.singleQuoted)"
case .notEnoughDataToGenerateBundle(let options, let underlyingError):
var symbolGraphFileList = options.additionalSymbolGraphFiles.reduce("") { $0 + "\n\t" + $1.path }
if !symbolGraphFileList.isEmpty {
symbolGraphFileList += "\n"
}
var errorMessage = """
The information provided as command line arguments is not enough to generate a documentation bundle:
"""
if let underlyingError {
errorMessage += """
\((underlyingError as? DescribedError)?.errorDescription ?? underlyingError.localizedDescription)
"""
} else {
errorMessage += """
\(options.infoPlistFallbacks.sorted(by: { lhs, rhs in lhs.key < rhs.key }).map { "\($0.key) : '\($0.value)'" }.joined(separator: "\n"))
Additional symbol graph files: [\(symbolGraphFileList)]
"""
}
return errorMessage
}
}
}
public func contentsOfURL(_ url: URL) throws -> Data {
if DocumentationBundleFileTypes.isMarkupFile(url), let content = generatedMarkdownFiles[url.deletingPathExtension().lastPathComponent] {
return content
} else if DocumentationBundleFileTypes.isSymbolGraphFile(url) {
guard let data = symbolGraphDataLoader(url) else {
throw Error.unableToLoadSymbolGraphData(url: url)
}
return data
} else {
preconditionFailure("Unexpected url '\(url)'.")
}
}
}
/// 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)
}
}
|
