Skip to content
This repository was archived by the owner on Jun 1, 2023. It is now read-only.

Commit f49b9d7

Browse files
matttmattt
authored
Merge pull request #93 from SwiftDocOrg/base-url-reimplementation
Reimplement base URL support without <base> tag
2 parents 137d67f + 7074084 commit f49b9d7

19 files changed

+138
-75
lines changed

‎Changelog.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
1010
### Added
1111

1212
- Added `--base-url` option.
13-
#65 by @kean.
13+
#65 by @kean and #93 by @mattt.
1414
- Added asset pipeline for CSS assets.
1515
#49 by @kaishin.
1616
- Add `swift-doc` version number to command and generated output.

‎README.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,7 @@ $ make install
6969

7070
OVERVIEW: Generates Swift documentation
7171

72-
USAGE: swift doc generate [<inputs> ...] --module-name <module-name> [--output <output>] [--format <format>]
72+
USAGE: swift doc generate [<inputs> ...] --module-name <module-name> [--output <output>] [--format <format>] [--base-url <base-url>]
7373

7474
ARGUMENTS:
7575
<inputs> One or more paths to Swift files
@@ -80,6 +80,8 @@ $ make install
8080
-o, --output <output> The path for generated output (default:
8181
.build/documentation)
8282
-f, --format <format> The output format (default: commonmark)
83+
--base-url <base-url> The base URL used for all relative URLs in generated
84+
documents. (default: /)
8385
-h, --help Show help information.
8486

8587
The `generate` subcommand

‎Sources/swift-doc/Extensions/SwiftDoc+Extensions.swift‎

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -15,10 +15,6 @@ extension Symbol {
1515
node.height = 0.5
1616
node.fixedSize = .shape
1717

18-
if !(api is Unknown) {
19-
node.href = "/" + path(for: self)
20-
}
21-
2218
switch api {
2319
case let `class` as Class:
2420
node.class = "class"
@@ -40,7 +36,7 @@ extension Symbol {
4036
return node
4137
}
4238

43-
func graph(in module: Module) -> Graph {
39+
func graph(in module: Module, baseURL: String) -> Graph {
4440
var graph = Graph(directed: true)
4541

4642
let relationships = module.interface.relationships.filter {
@@ -49,6 +45,11 @@ extension Symbol {
4945
}
5046

5147
var symbolNode = self.node
48+
49+
if !(api is Unknown) {
50+
symbolNode.href = path(for: self, with: baseURL)
51+
}
52+
5253
symbolNode.strokeWidth = 3.0
5354
symbolNode.class = [symbolNode.class, "current"].compactMap { $0 }.joined(separator: " ")
5455

‎Sources/swift-doc/Subcommands/Generate.swift‎

Lines changed: 10 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@ extension SwiftDoc {
4343

4444
func run() throws {
4545
let module = try Module(name: options.moduleName, paths: options.inputs)
46+
let baseURL = options.baseURL
4647

4748
let outputDirectoryURL = URL(fileURLWithPath: options.output)
4849
try fileManager.createDirectory(at: outputDirectoryURL, withIntermediateDirectories: true, attributes: fileAttributes)
@@ -56,9 +57,9 @@ extension SwiftDoc {
5657
for symbol in module.interface.topLevelSymbols.filter({ $0.isPublic }) {
5758
switch symbol.api {
5859
case is Class, is Enumeration, is Structure, is Protocol:
59-
pages[path(for: symbol)] = TypePage(module: module, symbol: symbol)
60+
pages[route(for: symbol)] = TypePage(module: module, symbol: symbol, baseURL: baseURL)
6061
case let `typealias` as Typealias:
61-
pages[path(for: `typealias`.name)] = TypealiasPage(module: module, symbol: symbol)
62+
pages[route(for: `typealias`.name)] = TypealiasPage(module: module, symbol: symbol, baseURL: baseURL)
6263
case let function as Function where !function.isOperator:
6364
globals[function.name, default: []] += [symbol]
6465
case let variable as Variable:
@@ -69,7 +70,7 @@ extension SwiftDoc {
6970
}
7071

7172
for (name, symbols) in globals {
72-
pages[path(for: name)] = GlobalPage(module: module, name: name, symbols: symbols)
73+
pages[route(for: name)] = GlobalPage(module: module, name: name, symbols: symbols, baseURL: baseURL)
7374
}
7475

7576
guard !pages.isEmpty else {
@@ -87,15 +88,15 @@ extension SwiftDoc {
8788
}
8889

8990
let url = outputDirectoryURL.appendingPathComponent(filename)
90-
try page.write(to: url, format: format, baseURL: options.baseURL)
91+
try page.write(to: url, format: format)
9192
} else {
9293
switch format {
9394
case .commonmark:
94-
pages["Home"] = HomePage(module: module)
95-
pages["_Sidebar"] = SidebarPage(module: module)
96-
pages["_Footer"] = FooterPage()
95+
pages["Home"] = HomePage(module: module, baseURL: baseURL)
96+
pages["_Sidebar"] = SidebarPage(module: module, baseURL: baseURL)
97+
pages["_Footer"] = FooterPage(baseURL: baseURL)
9798
case .html:
98-
pages["Home"] = HomePage(module: module)
99+
pages["Home"] = HomePage(module: module, baseURL: baseURL)
99100
}
100101

101102
try pages.map { $0 }.parallelForEach {
@@ -110,7 +111,7 @@ extension SwiftDoc {
110111
}
111112

112113
let url = outputDirectoryURL.appendingPathComponent(filename)
113-
try $0.value.write(to: url, format: format, baseURL: options.baseURL)
114+
try $0.value.write(to: url, format: format)
114115
}
115116
}
116117

‎Sources/swift-doc/Supporting Types/Components/Abstract.swift‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -6,9 +6,11 @@ import HypertextLiteral
66

77
struct Abstract: Component {
88
var symbol: Symbol
9+
let baseURL: String
910

10-
init(for symbol: Symbol) {
11+
init(for symbol: Symbol, baseURL: String) {
1112
self.symbol = symbol
13+
self.baseURL = baseURL
1214
}
1315

1416
// MARK: - Component
@@ -18,7 +20,7 @@ struct Abstract: Component {
1820
return Fragment {
1921
List.Item {
2022
Paragraph {
21-
Link(urlString: path(for: symbol), text: symbol.id.description)
23+
Link(urlString: path(for: symbol, with: baseURL), text: symbol.id.description)
2224
Text { ":" }
2325
}
2426

@@ -31,7 +33,7 @@ struct Abstract: Component {
3133
return Fragment {
3234
List.Item {
3335
Paragraph {
34-
Link(urlString: path(for: symbol), text: symbol.id.description)
36+
Link(urlString: path(for: symbol, with: baseURL), text: symbol.id.description)
3537
}
3638
}
3739
}
@@ -43,7 +45,7 @@ struct Abstract: Component {
4345

4446
return #"""
4547
<dt class="\#(descriptor)">
46-
<a href=\#(path(for: symbol)) title="\#(descriptor) - \#(symbol.id.description)">
48+
<a href=\#(path(for: symbol, with: baseURL)) title="\#(descriptor) - \#(symbol.id.description)">
4749
\#(softbreak(symbol.id.description))
4850
</a>
4951
</dt>

‎Sources/swift-doc/Supporting Types/Components/Declaration.swift‎

Lines changed: 4 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,10 +9,12 @@ import Xcode
99
struct Declaration: Component {
1010
var symbol: Symbol
1111
var module: Module
12+
let baseURL: String
1213

13-
init(of symbol: Symbol, in module: Module) {
14+
init(of symbol: Symbol, in module: Module, baseURL: String) {
1415
self.symbol = symbol
1516
self.module = module
17+
self.baseURL = baseURL
1618
}
1719

1820
// MARK: - Component
@@ -27,7 +29,7 @@ struct Declaration: Component {
2729

2830
var html: HypertextLiteral.HTML {
2931
var html = try! SwiftSyntaxHighlighter.highlight(source: symbol.declaration, using: Xcode.self)
30-
html = linkCodeElements(of: html, for: symbol, in: module)
32+
html = linkCodeElements(of: html, for: symbol, in: module, with: baseURL)
3133
return HTML(html)
3234
}
3335
}

‎Sources/swift-doc/Supporting Types/Components/Documentation.swift‎

Lines changed: 12 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -10,10 +10,12 @@ import Xcode
1010
struct Documentation: Component {
1111
var symbol: Symbol
1212
var module: Module
13+
let baseURL: String
1314

14-
init(for symbol: Symbol, in module: Module) {
15+
init(for symbol: Symbol, in module: Module, baseURL: String) {
1516
self.symbol = symbol
1617
self.module = module
18+
self.baseURL = baseURL
1719
}
1820

1921
// MARK: - Component
@@ -37,10 +39,10 @@ struct Documentation: Component {
3739
Fragment { "\(documentation.summary!)" }
3840
}
3941

40-
Declaration(of: symbol, in: module)
42+
Declaration(of: symbol, in: module, baseURL: baseURL)
4143

4244
ForEach(in: documentation.discussionParts) { part in
43-
DiscussionPart(part, for: symbol, in: module)
45+
DiscussionPart(part, for: symbol, in: module, baseURL: baseURL)
4446
}
4547

4648
if !documentation.parameters.isEmpty {
@@ -83,7 +85,7 @@ struct Documentation: Component {
8385

8486
var fragments: [HypertextLiteralConvertible] = []
8587

86-
fragments.append(Declaration(of: symbol, in: module))
88+
fragments.append(Declaration(of: symbol, in: module, baseURL: baseURL))
8789

8890
if let summary = documentation.summary {
8991
fragments.append(#"""
@@ -97,7 +99,7 @@ struct Documentation: Component {
9799
fragments.append(#"""
98100
<div class="discussion">
99101
\#(documentation.discussionParts.compactMap { part -> HTML? in
100-
DiscussionPart(part, for: symbol, in: module).html
102+
DiscussionPart(part, for: symbol, in: module, baseURL: baseURL).html
101103
})
102104
</div>
103105
"""# as HypertextLiteral.HTML)
@@ -178,11 +180,13 @@ extension Documentation {
178180
var symbol: Symbol
179181
var module: Module
180182
var part: SwiftMarkup.DiscussionPart
183+
let baseURL: String
181184

182-
init(_ part: SwiftMarkup.DiscussionPart, for symbol: Symbol, in module: Module) {
185+
init(_ part: SwiftMarkup.DiscussionPart, for symbol: Symbol, in module: Module, baseURL: String) {
183186
self.part = part
184187
self.symbol = symbol
185188
self.module = module
189+
self.baseURL = baseURL
186190
}
187191

188192
// MARK: - Component
@@ -238,11 +242,11 @@ extension Documentation {
238242
let source = codeBlock.literal
239243
{
240244
var html = try! SwiftSyntaxHighlighter.highlight(source: source, using: Xcode.self)
241-
html = linkCodeElements(of: html, for: symbol, in: module)
245+
html = linkCodeElements(of: html, for: symbol, in: module, with: baseURL)
242246
return HTML(html)
243247
} else {
244248
var html = codeBlock.render(format: .html, options: [.unsafe])
245-
html = linkCodeElements(of: html, for: symbol, in: module)
249+
html = linkCodeElements(of: html, for: symbol, in: module, with: baseURL)
246250
return HTML(html)
247251
}
248252
case .heading(let heading):

‎Sources/swift-doc/Supporting Types/Components/Members.swift‎

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ import HypertextLiteral
77
struct Members: Component {
88
var symbol: Symbol
99
var module: Module
10+
let baseURL: String
1011

1112
var members: [Symbol]
1213

@@ -17,9 +18,11 @@ struct Members: Component {
1718
var methods: [Symbol]
1819
var genericallyConstrainedMembers: [[GenericRequirement] : [Symbol]]
1920

20-
init(of symbol: Symbol, in module: Module) {
21+
init(of symbol: Symbol, in module: Module, baseURL: String) {
2122
self.symbol = symbol
2223
self.module = module
24+
self.baseURL = baseURL
25+
2326
self.members = module.interface.members(of: symbol).filter { $0.extension?.genericRequirements.isEmpty != false }
2427

2528
self.typealiases = members.filter { $0.api is Typealias }
@@ -55,7 +58,7 @@ struct Members: Component {
5558
Heading {
5659
Code { member.name }
5760
}
58-
Documentation(for: member, in: module)
61+
Documentation(for: member, in: module, baseURL: baseURL)
5962
}
6063
}
6164
}
@@ -72,7 +75,7 @@ struct Members: Component {
7275
Section {
7376
ForEach(in: members) { member in
7477
Heading { member.name }
75-
Documentation(for: member, in: module)
78+
Documentation(for: member, in: module, baseURL: baseURL)
7679
}
7780
}
7881
}
@@ -97,7 +100,7 @@ struct Members: Component {
97100
<h3>
98101
<code>\#(softbreak(member.name))</code>
99102
</h3>
100-
\#(Documentation(for: member, in: module).html)
103+
\#(Documentation(for: member, in: module, baseURL: baseURL).html)
101104
</div>
102105
"""#
103106
})
@@ -117,7 +120,7 @@ struct Members: Component {
117120
\#(members.map { member -> HypertextLiteral.HTML in
118121
#"""
119122
<h4>\#(softbreak(member.name))</h4>
120-
\#(Documentation(for: member, in: module).html)
123+
\#(Documentation(for: member, in: module, baseURL: baseURL).html)
121124
"""#
122125
})
123126
</section>

‎Sources/swift-doc/Supporting Types/Components/Relationships.swift‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -28,16 +28,18 @@ extension StringBuilder {
2828
struct Relationships: Component {
2929
var module: Module
3030
var symbol: Symbol
31+
let baseURL: String
3132
var inheritedTypes: [Symbol]
3233

33-
init(of symbol: Symbol, in module: Module) {
34+
init(of symbol: Symbol, in module: Module, baseURL: String) {
3435
self.module = module
3536
self.symbol = symbol
3637
self.inheritedTypes = module.interface.typesInherited(by: symbol) + module.interface.typesConformed(by: symbol)
38+
self.baseURL = baseURL
3739
}
3840

3941
var graphHTML: HypertextLiteral.HTML? {
40-
var graph = symbol.graph(in: module)
42+
var graph = symbol.graph(in: module, baseURL: baseURL)
4143
guard !graph.edges.isEmpty else { return nil }
4244

4345
graph.aspectRatio = 0.125
@@ -80,7 +82,7 @@ struct Relationships: Component {
8082
if type.api is Unknown {
8183
return "`\(type.id)`"
8284
} else {
83-
return "[`\(type.id)`](\(path(for: type)))"
85+
return "[`\(type.id)`](\(path(for: type, with: baseURL)))"
8486
}
8587
}.joined(separator: ", "))
8688
"""#
@@ -118,7 +120,7 @@ struct Relationships: Component {
118120
"""#
119121
} else {
120122
return #"""
121-
<dt class="\#(descriptor)"><code><a href="\#(path(for: symbol))">\#(symbol.id)</a></code></dt>
123+
<dt class="\#(descriptor)"><code><a href="\#(path(for: symbol, with: baseURL))">\#(symbol.id)</a></code></dt>
122124
<dd>\#(commonmark: symbol.documentation?.summary ?? "")</dd>
123125
"""#
124126
}

‎Sources/swift-doc/Supporting Types/Components/Requirements.swift‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,12 @@ import HypertextLiteral
77
struct Requirements: Component {
88
var symbol: Symbol
99
var module: Module
10+
let baseURL: String
1011

11-
init(of symbol: Symbol, in module: Module) {
12+
init(of symbol: Symbol, in module: Module, baseURL: String) {
1213
self.symbol = symbol
1314
self.module = module
15+
self.baseURL = baseURL
1416
}
1517

1618
var sections: [(title: String, requirements: [Symbol])] {
@@ -31,7 +33,7 @@ struct Requirements: Component {
3133
Heading { section.title }
3234
ForEach(in: section.requirements) { requirement in
3335
Heading { requirement.name }
34-
Documentation(for: requirement, in: module)
36+
Documentation(for: requirement, in: module, baseURL: baseURL)
3537
}
3638
}
3739
}
@@ -53,7 +55,7 @@ struct Requirements: Component {
5355
<h3>
5456
<code>\#(softbreak(member.name))</code>
5557
</h3>
56-
\#(Documentation(for: member, in: module).html)
58+
\#(Documentation(for: member, in: module, baseURL: baseURL).html)
5759
</div>
5860
"""#
5961
})

0 commit comments

Comments
 (0)