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
150
|
/*
This source file is part of the Swift.org open source project
Copyright (c) 2021-2024 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
/**
A documentation bundle.
A documentation bundle stores all of the authored content and metadata for a collection of topics and/or frameworks.
No content data is immediately loaded when creating a `DocumentationBundle` except for its `Info.plist`. Its purpose is to provide paths on disk for documentation resources.
## Topics
### Bundle Metadata
- ``displayName``
- ``identifier``
- ``version``
*/
public struct DocumentationBundle {
public enum PropertyListError: DescribedError {
case invalidVersionString(String)
case keyNotFound(String)
public var errorDescription: String {
switch self {
case .invalidVersionString(let versionString):
return "'\(versionString)' is not a valid version string"
case .keyNotFound(let name):
return "Expected key \(name.singleQuoted) not found"
}
}
}
/// Information about this documentation bundle that's unrelated to its documentation content.
public let info: Info
/**
The bundle's human-readable display name.
*/
public var displayName: String {
info.displayName
}
/**
The documentation bundle identifier.
An identifier string that specifies the app type of the bundle. The string should be in reverse DNS format using only the Roman alphabet in upper and lower case (A–Z, a–z), the dot (“.”), and the hyphen (“-”).
*/
public var identifier: String {
info.identifier
}
/**
The documentation bundle's version.
It's not safe to make computations based on assumptions about the format of bundle's version. The version can be in any format.
*/
public var version: String? {
info.version
}
/// Code listings extracted from the documented modules' source, indexed by their identifier.
public var attributedCodeListings: [String: AttributedCodeListing]
/// Symbol Graph JSON files for the modules documented by this bundle.
public let symbolGraphURLs: [URL]
/// DocC Markup files of the bundle.
public let markupURLs: [URL]
/// Miscellaneous resources of the bundle.
public let miscResourceURLs: [URL]
/// A custom HTML file to use as the header for rendered output.
public let customHeader: URL?
/// A custom HTML file to use as the footer for rendered output.
public let customFooter: URL?
/// 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 bundle's documentation is hosted in a known location.
*/
public let baseURL: URL
/// Creates a documentation bundle.
///
/// - Parameters:
/// - info: Information about the bundle.
/// - baseURL: A URL prefix to be appended to the relative presentation URL.
/// - attributedCodeListings: Code listings extracted from the documented modules' source, indexed by their identifier.
/// - symbolGraphURLs: Symbol Graph JSON files for the modules documented by the bundle.
/// - markupURLs: DocC Markup files of the bundle.
/// - miscResourceURLs: Miscellaneous resources of the bundle.
/// - 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.
public init(
info: Info,
baseURL: URL = URL(string: "/")!,
attributedCodeListings: [String: AttributedCodeListing] = [:],
symbolGraphURLs: [URL],
markupURLs: [URL],
miscResourceURLs: [URL],
customHeader: URL? = nil,
customFooter: URL? = nil,
themeSettings: URL? = nil
) {
self.info = info
self.baseURL = baseURL
self.attributedCodeListings = attributedCodeListings
self.symbolGraphURLs = symbolGraphURLs
self.markupURLs = markupURLs
self.miscResourceURLs = miscResourceURLs
self.customHeader = customHeader
self.customFooter = customFooter
self.themeSettings = themeSettings
self.rootReference = ResolvedTopicReference(bundleIdentifier: info.identifier, path: "/", sourceLanguage: .swift)
self.documentationRootReference = ResolvedTopicReference(bundleIdentifier: info.identifier, path: NodeURLGenerator.Path.documentationFolder, sourceLanguage: .swift)
self.tutorialsRootReference = ResolvedTopicReference(bundleIdentifier: info.identifier, path: NodeURLGenerator.Path.tutorialsFolder, sourceLanguage: .swift)
self.technologyTutorialsRootReference = tutorialsRootReference.appendingPath(urlReadablePath(info.displayName))
self.articlesDocumentationRootReference = documentationRootReference.appendingPath(urlReadablePath(info.displayName))
}
public private(set) var rootReference: ResolvedTopicReference
/// Default path to resolve symbol links.
public private(set) var documentationRootReference: ResolvedTopicReference
/// Default path to resolve technology links.
public var tutorialsRootReference: ResolvedTopicReference
/// Default path to resolve tutorials.
public var technologyTutorialsRootReference: ResolvedTopicReference
/// Default path to resolve articles.
public var articlesDocumentationRootReference: ResolvedTopicReference
}
|
