From 6b622be78d9fde88b539ceab25c44621713dbb9f Mon Sep 17 00:00:00 2001 From: Mattt Date: Fri, 24 Apr 2020 12:56:23 -0700 Subject: [PATCH 1/4] Replace with baseURL parameter for path helper --- .../Extensions/SwiftDoc+Extensions.swift | 11 +++++----- Sources/swift-doc/Subcommands/Generate.swift | 19 +++++++++--------- .../Components/Declaration.swift | 6 ++++-- .../Components/Documentation.swift | 12 ++++++----- .../Supporting Types/Components/Members.swift | 13 +++++++----- .../Components/Relationships.swift | 10 ++++++---- .../Components/Requirements.swift | 8 +++++--- .../swift-doc/Supporting Types/Helpers.swift | 4 ++-- .../swift-doc/Supporting Types/Layout.swift | 9 ++++----- Sources/swift-doc/Supporting Types/Page.swift | 20 +++++++++++++------ .../Supporting Types/Pages/FooterPage.swift | 6 ++++++ .../Supporting Types/Pages/GlobalPage.swift | 8 +++++--- .../Supporting Types/Pages/HomePage.swift | 10 ++++++---- .../Supporting Types/Pages/SidebarPage.swift | 6 ++++-- .../Supporting Types/Pages/TypePage.swift | 20 ++++++++++--------- .../Pages/TypealiasPage.swift | 8 +++++--- 16 files changed, 103 insertions(+), 67 deletions(-) diff --git a/Sources/swift-doc/Extensions/SwiftDoc+Extensions.swift b/Sources/swift-doc/Extensions/SwiftDoc+Extensions.swift index 6a0c306a..9222248a 100644 --- a/Sources/swift-doc/Extensions/SwiftDoc+Extensions.swift +++ b/Sources/swift-doc/Extensions/SwiftDoc+Extensions.swift @@ -15,10 +15,6 @@ extension Symbol { node.height = 0.5 node.fixedSize = .shape - if !(api is Unknown) { - node.href = "/" + path(for: self) - } - switch api { case let `class` as Class: node.class = "class" @@ -40,7 +36,7 @@ extension Symbol { return node } - func graph(in module: Module) -> Graph { + func graph(in module: Module, baseURL: String) -> Graph { var graph = Graph(directed: true) let relationships = module.interface.relationships.filter { @@ -49,6 +45,11 @@ extension Symbol { } var symbolNode = self.node + + if !(api is Unknown) { + symbolNode.href = path(for: self, with: baseURL) + } + symbolNode.strokeWidth = 3.0 symbolNode.class = [symbolNode.class, "current"].compactMap { $0 }.joined(separator: " ") diff --git a/Sources/swift-doc/Subcommands/Generate.swift b/Sources/swift-doc/Subcommands/Generate.swift index 3001b641..faf94073 100644 --- a/Sources/swift-doc/Subcommands/Generate.swift +++ b/Sources/swift-doc/Subcommands/Generate.swift @@ -43,6 +43,7 @@ extension SwiftDoc { func run() throws { let module = try Module(name: options.moduleName, paths: options.inputs) + let baseURL = options.baseURL let outputDirectoryURL = URL(fileURLWithPath: options.output) try fileManager.createDirectory(at: outputDirectoryURL, withIntermediateDirectories: true, attributes: fileAttributes) @@ -56,9 +57,9 @@ extension SwiftDoc { for symbol in module.interface.topLevelSymbols.filter({ $0.isPublic }) { switch symbol.api { case is Class, is Enumeration, is Structure, is Protocol: - pages[path(for: symbol)] = TypePage(module: module, symbol: symbol) + pages[path(for: symbol, with: baseURL)] = TypePage(module: module, symbol: symbol, baseURL: baseURL) case let `typealias` as Typealias: - pages[path(for: `typealias`.name)] = TypealiasPage(module: module, symbol: symbol) + pages[path(for: `typealias`.name, with: baseURL)] = TypealiasPage(module: module, symbol: symbol, baseURL: baseURL) case let function as Function where !function.isOperator: globals[function.name, default: []] += [symbol] case let variable as Variable: @@ -69,7 +70,7 @@ extension SwiftDoc { } for (name, symbols) in globals { - pages[path(for: name)] = GlobalPage(module: module, name: name, symbols: symbols) + pages[path(for: name, with: baseURL)] = GlobalPage(module: module, name: name, symbols: symbols, baseURL: baseURL) } guard !pages.isEmpty else { @@ -87,15 +88,15 @@ extension SwiftDoc { } let url = outputDirectoryURL.appendingPathComponent(filename) - try page.write(to: url, format: format, baseURL: options.baseURL) + try page.write(to: url, format: format) } else { switch format { case .commonmark: - pages["Home"] = HomePage(module: module) - pages["_Sidebar"] = SidebarPage(module: module) - pages["_Footer"] = FooterPage() + pages["Home"] = HomePage(module: module, baseURL: baseURL) + pages["_Sidebar"] = SidebarPage(module: module, baseURL: baseURL) + pages["_Footer"] = FooterPage(baseURL: baseURL) case .html: - pages["Home"] = HomePage(module: module) + pages["Home"] = HomePage(module: module, baseURL: baseURL) } try pages.map { $0 }.parallelForEach { @@ -110,7 +111,7 @@ extension SwiftDoc { } let url = outputDirectoryURL.appendingPathComponent(filename) - try $0.value.write(to: url, format: format, baseURL: options.baseURL) + try $0.value.write(to: url, format: format) } } diff --git a/Sources/swift-doc/Supporting Types/Components/Declaration.swift b/Sources/swift-doc/Supporting Types/Components/Declaration.swift index 94acc437..2c1433d1 100644 --- a/Sources/swift-doc/Supporting Types/Components/Declaration.swift +++ b/Sources/swift-doc/Supporting Types/Components/Declaration.swift @@ -9,10 +9,12 @@ import Xcode struct Declaration: Component { var symbol: Symbol var module: Module + let baseURL: String - init(of symbol: Symbol, in module: Module) { + init(of symbol: Symbol, in module: Module, baseURL: String) { self.symbol = symbol self.module = module + self.baseURL = baseURL } // MARK: - Component @@ -27,7 +29,7 @@ struct Declaration: Component { var html: HypertextLiteral.HTML { var html = try! SwiftSyntaxHighlighter.highlight(source: symbol.declaration, using: Xcode.self) - html = linkCodeElements(of: html, for: symbol, in: module) + html = linkCodeElements(of: html, for: symbol, in: module, with: baseURL) return HTML(html) } } diff --git a/Sources/swift-doc/Supporting Types/Components/Documentation.swift b/Sources/swift-doc/Supporting Types/Components/Documentation.swift index 132ffc89..77a9a190 100644 --- a/Sources/swift-doc/Supporting Types/Components/Documentation.swift +++ b/Sources/swift-doc/Supporting Types/Components/Documentation.swift @@ -10,10 +10,12 @@ import Xcode struct Documentation: Component { var symbol: Symbol var module: Module + let baseURL: String - init(for symbol: Symbol, in module: Module) { + init(for symbol: Symbol, in module: Module, baseURL: String) { self.symbol = symbol self.module = module + self.baseURL = baseURL } // MARK: - Component @@ -37,7 +39,7 @@ struct Documentation: Component { Fragment { "\(documentation.summary!)" } } - Declaration(of: symbol, in: module) + Declaration(of: symbol, in: module, baseURL: baseURL) ForEach(in: documentation.discussionParts) { part in if part is SwiftMarkup.Documentation.Callout { @@ -87,7 +89,7 @@ struct Documentation: Component { var fragments: [HypertextLiteralConvertible] = [] - fragments.append(Declaration(of: symbol, in: module)) + fragments.append(Declaration(of: symbol, in: module, baseURL: baseURL)) if let summary = documentation.summary { fragments.append(#""" @@ -111,11 +113,11 @@ struct Documentation: Component { let source = codeBlock.literal { var html = try! SwiftSyntaxHighlighter.highlight(source: source, using: Xcode.self) - html = linkCodeElements(of: html, for: symbol, in: module) + html = linkCodeElements(of: html, for: symbol, in: module, with: baseURL) return HTML(html) } else { var html = (try! CommonMark.Document(part)).render(format: .html, options: [.unsafe]) - html = linkCodeElements(of: html, for: symbol, in: module) + html = linkCodeElements(of: html, for: symbol, in: module, with: baseURL) return HTML(html) } } else { diff --git a/Sources/swift-doc/Supporting Types/Components/Members.swift b/Sources/swift-doc/Supporting Types/Components/Members.swift index d1c607d8..ff3d9e71 100644 --- a/Sources/swift-doc/Supporting Types/Components/Members.swift +++ b/Sources/swift-doc/Supporting Types/Components/Members.swift @@ -7,6 +7,7 @@ import HypertextLiteral struct Members: Component { var symbol: Symbol var module: Module + let baseURL: String var members: [Symbol] @@ -17,9 +18,11 @@ struct Members: Component { var methods: [Symbol] var genericallyConstrainedMembers: [[GenericRequirement] : [Symbol]] - init(of symbol: Symbol, in module: Module) { + init(of symbol: Symbol, in module: Module, baseURL: String) { self.symbol = symbol self.module = module + self.baseURL = baseURL + self.members = module.interface.members(of: symbol).filter { $0.extension?.genericRequirements.isEmpty != false } self.typealiases = members.filter { $0.api is Typealias } @@ -55,7 +58,7 @@ struct Members: Component { Heading { Code { member.name } } - Documentation(for: member, in: module) + Documentation(for: member, in: module, baseURL: baseURL) } } } @@ -72,7 +75,7 @@ struct Members: Component { Section { ForEach(in: members) { member in Heading { member.name } - Documentation(for: member, in: module) + Documentation(for: member, in: module, baseURL: baseURL) } } } @@ -97,7 +100,7 @@ struct Members: Component {

\#(softbreak(member.name))

- \#(Documentation(for: member, in: module).html) + \#(Documentation(for: member, in: module, baseURL: baseURL).html) """# }) @@ -117,7 +120,7 @@ struct Members: Component { \#(members.map { member -> HypertextLiteral.HTML in #"""

\#(softbreak(member.name))

- \#(Documentation(for: member, in: module).html) + \#(Documentation(for: member, in: module, baseURL: baseURL).html) """# }) diff --git a/Sources/swift-doc/Supporting Types/Components/Relationships.swift b/Sources/swift-doc/Supporting Types/Components/Relationships.swift index e347f871..647c5846 100644 --- a/Sources/swift-doc/Supporting Types/Components/Relationships.swift +++ b/Sources/swift-doc/Supporting Types/Components/Relationships.swift @@ -28,16 +28,18 @@ extension StringBuilder { struct Relationships: Component { var module: Module var symbol: Symbol + let baseURL: String var inheritedTypes: [Symbol] - init(of symbol: Symbol, in module: Module) { + init(of symbol: Symbol, in module: Module, baseURL: String) { self.module = module self.symbol = symbol self.inheritedTypes = module.interface.typesInherited(by: symbol) + module.interface.typesConformed(by: symbol) + self.baseURL = baseURL } var graphHTML: HypertextLiteral.HTML? { - var graph = symbol.graph(in: module) + var graph = symbol.graph(in: module, baseURL: baseURL) guard !graph.edges.isEmpty else { return nil } graph.aspectRatio = 0.125 @@ -80,7 +82,7 @@ struct Relationships: Component { if type.api is Unknown { return "`\(type.id)`" } else { - return "[`\(type.id)`](\(path(for: type)))" + return "[`\(type.id)`](\(path(for: type, with: baseURL)))" } }.joined(separator: ", ")) """# @@ -118,7 +120,7 @@ struct Relationships: Component { """# } else { return #""" -
\#(symbol.id)
+
\#(symbol.id)
\#(commonmark: symbol.documentation?.summary ?? "")
"""# } diff --git a/Sources/swift-doc/Supporting Types/Components/Requirements.swift b/Sources/swift-doc/Supporting Types/Components/Requirements.swift index 4f24d4ce..2a3ca426 100644 --- a/Sources/swift-doc/Supporting Types/Components/Requirements.swift +++ b/Sources/swift-doc/Supporting Types/Components/Requirements.swift @@ -7,10 +7,12 @@ import HypertextLiteral struct Requirements: Component { var symbol: Symbol var module: Module + let baseURL: String - init(of symbol: Symbol, in module: Module) { + init(of symbol: Symbol, in module: Module, baseURL: String) { self.symbol = symbol self.module = module + self.baseURL = baseURL } var sections: [(title: String, requirements: [Symbol])] { @@ -31,7 +33,7 @@ struct Requirements: Component { Heading { section.title } ForEach(in: section.requirements) { requirement in Heading { requirement.name } - Documentation(for: requirement, in: module) + Documentation(for: requirement, in: module, baseURL: baseURL) } } } @@ -53,7 +55,7 @@ struct Requirements: Component {

\#(softbreak(member.name))

- \#(Documentation(for: member, in: module).html) + \#(Documentation(for: member, in: module, baseURL: baseURL).html) """# }) diff --git a/Sources/swift-doc/Supporting Types/Helpers.swift b/Sources/swift-doc/Supporting Types/Helpers.swift index 695509b7..430bdaa1 100644 --- a/Sources/swift-doc/Supporting Types/Helpers.swift +++ b/Sources/swift-doc/Supporting Types/Helpers.swift @@ -2,7 +2,7 @@ import Foundation import SwiftDoc import HTML -public func linkCodeElements(of html: String, for symbol: Symbol, in module: Module) -> String { +public func linkCodeElements(of html: String, for symbol: Symbol, in module: Module, with baseURL: String) -> String { let document = try! Document(string: html.description)! for element in document.search(xpath: "//code | //pre/code//span[contains(@class,'type')]") { guard let name = element.content else { continue } @@ -12,7 +12,7 @@ public func linkCodeElements(of html: String, for symbol: Symbol, in module: Mod let candidate = candidates.filter({ $0 != symbol }).first { let a = Element(name: "a") - a["href"] = path(for: candidate) + a["href"] = path(for: candidate, with: baseURL) element.wrap(inside: a) } } diff --git a/Sources/swift-doc/Supporting Types/Layout.swift b/Sources/swift-doc/Supporting Types/Layout.swift index f82bf6e7..b0c22e70 100644 --- a/Sources/swift-doc/Supporting Types/Layout.swift +++ b/Sources/swift-doc/Supporting Types/Layout.swift @@ -1,7 +1,7 @@ import HypertextLiteral import Foundation -func layout(_ page: Page, baseURL: String) -> HTML { +func layout(_ page: Page) -> HTML { let html = page.html return #""" @@ -11,12 +11,11 @@ func layout(_ page: Page, baseURL: String) -> HTML { \#(page.module.name) - \#(page.title) - - +
- + \#(page.module.name) @@ -45,7 +44,7 @@ func layout(_ page: Page, baseURL: String) -> HTML {
- \#(FooterPage().html) + \#(FooterPage(baseURL: page.baseURL).html)
diff --git a/Sources/swift-doc/Supporting Types/Page.swift b/Sources/swift-doc/Supporting Types/Page.swift index 639ddeae..3d13f5cf 100644 --- a/Sources/swift-doc/Supporting Types/Page.swift +++ b/Sources/swift-doc/Supporting Types/Page.swift @@ -8,6 +8,7 @@ import HypertextLiteral protocol Page: HypertextLiteralConvertible { var module: Module { get } + var baseURL: String { get } var title: String { get } var document: CommonMark.Document { get } var html: HypertextLiteral.HTML { get } @@ -19,13 +20,13 @@ extension Page { } extension Page { - func write(to url: URL, format: SwiftDoc.Generate.Format, baseURL: String) throws { + func write(to url: URL, format: SwiftDoc.Generate.Format) throws { let data: Data? switch format { case .commonmark: data = document.render(format: .commonmark).data(using: .utf8) case .html: - data = layout(self, baseURL: baseURL).description.data(using: .utf8) + data = layout(self).description.data(using: .utf8) } guard let filedata = data else { return } @@ -34,12 +35,19 @@ extension Page { } } -func path(for symbol: Symbol) -> String { - return path(for: symbol.id.description) +func path(for symbol: Symbol, with baseURL: String) -> String { + return path(for: symbol.id.description, with: baseURL) } -func path(for identifier: CustomStringConvertible) -> String { - return "\(identifier)".replacingOccurrences(of: ".", with: "_") +func path(for identifier: CustomStringConvertible, with baseURL: String) -> String { + var urlComponents = URLComponents(string: baseURL) + urlComponents?.path += "\(identifier)".replacingOccurrences(of: ".", with: "_") + guard let path = urlComponents?.string else { + logger.critical("Unable to construct path for \(identifier) with baseURL \(baseURL)") + fatalError() + } + + return path } func writeFile(_ data: Data, to url: URL) throws { diff --git a/Sources/swift-doc/Supporting Types/Pages/FooterPage.swift b/Sources/swift-doc/Supporting Types/Pages/FooterPage.swift index bc17928b..349eb137 100644 --- a/Sources/swift-doc/Supporting Types/Pages/FooterPage.swift +++ b/Sources/swift-doc/Supporting Types/Pages/FooterPage.swift @@ -18,6 +18,12 @@ fileprivate let timestampDateFormatter: DateFormatter = { fileprivate let href = "https://github.com/SwiftDocOrg/swift-doc" struct FooterPage: Page { + let baseURL: String + + init(baseURL: String) { + self.baseURL = baseURL + } + // MARK: - Page var document: CommonMark.Document { diff --git a/Sources/swift-doc/Supporting Types/Pages/GlobalPage.swift b/Sources/swift-doc/Supporting Types/Pages/GlobalPage.swift index e59f37a4..cd8dad0f 100644 --- a/Sources/swift-doc/Supporting Types/Pages/GlobalPage.swift +++ b/Sources/swift-doc/Supporting Types/Pages/GlobalPage.swift @@ -7,11 +7,13 @@ struct GlobalPage: Page { let module: Module let name: String let symbols: [Symbol] + let baseURL: String - init(module: Module, name: String, symbols: [Symbol]) { + init(module: Module, name: String, symbols: [Symbol], baseURL: String) { self.module = module self.name = name self.symbols = symbols + self.baseURL = baseURL } // MARK: - Page @@ -24,7 +26,7 @@ struct GlobalPage: Page { return Document { ForEach(in: symbols) { symbol in Heading { symbol.id.description } - Documentation(for: symbol, in: module) + Documentation(for: symbol, in: module, baseURL: baseURL) } } } @@ -46,7 +48,7 @@ struct GlobalPage: Page { \#(symbols.map { symbol in - Documentation(for: symbol, in: module).html + Documentation(for: symbol, in: module, baseURL: baseURL).html }) """# } diff --git a/Sources/swift-doc/Supporting Types/Pages/HomePage.swift b/Sources/swift-doc/Supporting Types/Pages/HomePage.swift index b7a976d8..2afc612d 100644 --- a/Sources/swift-doc/Supporting Types/Pages/HomePage.swift +++ b/Sources/swift-doc/Supporting Types/Pages/HomePage.swift @@ -5,6 +5,7 @@ import HypertextLiteral struct HomePage: Page { var module: Module + let baseURL: String var classes: [Symbol] = [] var enumerations: [Symbol] = [] @@ -15,8 +16,9 @@ struct HomePage: Page { var globalFunctions: [Symbol] = [] var globalVariables: [Symbol] = [] - init(module: Module) { + init(module: Module, baseURL: String) { self.module = module + self.baseURL = baseURL for symbol in module.interface.topLevelSymbols.filter({ $0.isPublic }) { switch symbol.api { @@ -69,7 +71,7 @@ struct HomePage: Page { if (!names.isEmpty) { Heading { heading } List(of: names.sorted()) { name in - Link(urlString: path(for: name), text: name) + Link(urlString: path(for: name, with: baseURL), text: name) } } } @@ -90,7 +92,7 @@ struct HomePage: Page { Heading { heading } List(of: names.sorted()) { name in - Link(urlString: path(for: name), text: softbreak(name)) + Link(urlString: path(for: name, with: baseURL), text: softbreak(name)) } } } @@ -163,7 +165,7 @@ struct HomePage: Page { let descriptor = String(describing: type(of: symbol.api)).lowercased() return #"""
- + \#(softbreak(symbol.id.description))
diff --git a/Sources/swift-doc/Supporting Types/Pages/SidebarPage.swift b/Sources/swift-doc/Supporting Types/Pages/SidebarPage.swift index 8c98b3af..7b71908b 100644 --- a/Sources/swift-doc/Supporting Types/Pages/SidebarPage.swift +++ b/Sources/swift-doc/Supporting Types/Pages/SidebarPage.swift @@ -5,6 +5,7 @@ import HypertextLiteral struct SidebarPage: Page { var module: Module + let baseURL: String var typeNames: Set = [] var protocolNames: Set = [] @@ -13,8 +14,9 @@ struct SidebarPage: Page { var globalFunctionNames: Set = [] var globalVariableNames: Set = [] - init(module: Module) { + init(module: Module, baseURL: String) { self.module = module + self.baseURL = baseURL for symbol in module.interface.topLevelSymbols.filter({ $0.isPublic }) { switch symbol.api { @@ -65,7 +67,7 @@ struct SidebarPage: Page { } List(of: section.names.sorted()) { name in - Link(urlString: "/" + path(for: name), text: name) + Link(urlString: path(for: name, with: baseURL), text: name) } Fragment { "" } diff --git a/Sources/swift-doc/Supporting Types/Pages/TypePage.swift b/Sources/swift-doc/Supporting Types/Pages/TypePage.swift index 6ed5f348..244e736a 100644 --- a/Sources/swift-doc/Supporting Types/Pages/TypePage.swift +++ b/Sources/swift-doc/Supporting Types/Pages/TypePage.swift @@ -6,11 +6,13 @@ import HypertextLiteral struct TypePage: Page { let module: Module let symbol: Symbol + let baseURL: String - init(module: Module, symbol: Symbol) { + init(module: Module, symbol: Symbol, baseURL: String) { precondition(symbol.api is Type) self.module = module self.symbol = symbol + self.baseURL = baseURL } // MARK: - Page @@ -23,10 +25,10 @@ struct TypePage: Page { return CommonMark.Document { Heading { symbol.id.description } - Documentation(for: symbol, in: module) - Relationships(of: symbol, in: module) - Members(of: symbol, in: module) - Requirements(of: symbol, in: module) + Documentation(for: symbol, in: module, baseURL: baseURL) + Relationships(of: symbol, in: module, baseURL: baseURL) + Members(of: symbol, in: module, baseURL: baseURL) + Requirements(of: symbol, in: module, baseURL: baseURL) } } @@ -37,10 +39,10 @@ struct TypePage: Page { \#(softbreak(symbol.id.description)) - \#(Documentation(for: symbol, in: module).html) - \#(Relationships(of: symbol, in: module).html) - \#(Members(of: symbol, in: module).html) - \#(Requirements(of: symbol, in: module).html) + \#(Documentation(for: symbol, in: module, baseURL: baseURL).html) + \#(Relationships(of: symbol, in: module, baseURL: baseURL).html) + \#(Members(of: symbol, in: module, baseURL: baseURL).html) + \#(Requirements(of: symbol, in: module, baseURL: baseURL).html) """# } } diff --git a/Sources/swift-doc/Supporting Types/Pages/TypealiasPage.swift b/Sources/swift-doc/Supporting Types/Pages/TypealiasPage.swift index a342fa0a..4c806727 100644 --- a/Sources/swift-doc/Supporting Types/Pages/TypealiasPage.swift +++ b/Sources/swift-doc/Supporting Types/Pages/TypealiasPage.swift @@ -6,11 +6,13 @@ import HypertextLiteral struct TypealiasPage: Page { let module: Module let symbol: Symbol + let baseURL: String - init(module: Module, symbol: Symbol) { + init(module: Module, symbol: Symbol, baseURL: String) { precondition(symbol.api is Typealias) self.module = module self.symbol = symbol + self.baseURL = baseURL } // MARK: - Page @@ -22,7 +24,7 @@ struct TypealiasPage: Page { var document: CommonMark.Document { Document { Heading { symbol.id.description } - Documentation(for: symbol, in: module) + Documentation(for: symbol, in: module, baseURL: baseURL) } } @@ -33,7 +35,7 @@ struct TypealiasPage: Page { \#(softbreak(symbol.id.description)) - \#(Documentation(for: symbol, in: module).html) + \#(Documentation(for: symbol, in: module, baseURL: baseURL).html) """# } } From 507436c736b08e5c92d36068373429825fb10432 Mon Sep 17 00:00:00 2001 From: Mattt Date: Fri, 24 Apr 2020 13:29:56 -0700 Subject: [PATCH 2/4] Update generate command usage in README --- README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 4b994efb..3ae7c96d 100644 --- a/README.md +++ b/README.md @@ -67,7 +67,7 @@ $ make install OVERVIEW: Generates Swift documentation - USAGE: swift-doc generate [ ...] --module-name [--output ] [--format ] + USAGE: swift-doc generate [ ...] --module-name [--output ] [--format ] [--base-url ] ARGUMENTS: One or more paths to Swift files @@ -78,6 +78,8 @@ $ make install -o, --output The path for generated output (default: .build/documentation) -f, --format The output format (default: commonmark) + --base-url The base URL used for all relative URLs in generated + documents. (default: /) -h, --help Show help information. The `generate` subcommand From 839f314f9ba5be347ed8034d78df9deec3f1dbd4 Mon Sep 17 00:00:00 2001 From: Mattt Date: Fri, 24 Apr 2020 13:30:11 -0700 Subject: [PATCH 3/4] Update changelog entry for --baseURL option --- Changelog.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Changelog.md b/Changelog.md index 4ef81e24..951da911 100644 --- a/Changelog.md +++ b/Changelog.md @@ -10,7 +10,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added - Added `--base-url` option. - #65 by @kean. + #65 by @kean and #93 by @mattt. - Added asset pipeline for CSS assets. #49 by @kaishin. From 7074084ba0928f073203c80483b0e39939a7fdce Mon Sep 17 00:00:00 2001 From: Mattt Date: Mon, 11 May 2020 11:55:24 -0700 Subject: [PATCH 4/4] Fix route resolution with base url and output option --- Sources/swift-doc/Subcommands/Generate.swift | 6 ++-- .../swift-doc/Supporting Types/Layout.swift | 2 +- Sources/swift-doc/Supporting Types/Page.swift | 29 ++++++++++++++++--- 3 files changed, 29 insertions(+), 8 deletions(-) diff --git a/Sources/swift-doc/Subcommands/Generate.swift b/Sources/swift-doc/Subcommands/Generate.swift index faf94073..16bb70d3 100644 --- a/Sources/swift-doc/Subcommands/Generate.swift +++ b/Sources/swift-doc/Subcommands/Generate.swift @@ -57,9 +57,9 @@ extension SwiftDoc { for symbol in module.interface.topLevelSymbols.filter({ $0.isPublic }) { switch symbol.api { case is Class, is Enumeration, is Structure, is Protocol: - pages[path(for: symbol, with: baseURL)] = TypePage(module: module, symbol: symbol, baseURL: baseURL) + pages[route(for: symbol)] = TypePage(module: module, symbol: symbol, baseURL: baseURL) case let `typealias` as Typealias: - pages[path(for: `typealias`.name, with: baseURL)] = TypealiasPage(module: module, symbol: symbol, baseURL: baseURL) + pages[route(for: `typealias`.name)] = TypealiasPage(module: module, symbol: symbol, baseURL: baseURL) case let function as Function where !function.isOperator: globals[function.name, default: []] += [symbol] case let variable as Variable: @@ -70,7 +70,7 @@ extension SwiftDoc { } for (name, symbols) in globals { - pages[path(for: name, with: baseURL)] = GlobalPage(module: module, name: name, symbols: symbols, baseURL: baseURL) + pages[route(for: name)] = GlobalPage(module: module, name: name, symbols: symbols, baseURL: baseURL) } guard !pages.isEmpty else { diff --git a/Sources/swift-doc/Supporting Types/Layout.swift b/Sources/swift-doc/Supporting Types/Layout.swift index b0c22e70..a9c940f2 100644 --- a/Sources/swift-doc/Supporting Types/Layout.swift +++ b/Sources/swift-doc/Supporting Types/Layout.swift @@ -11,7 +11,7 @@ func layout(_ page: Page) -> HTML { \#(page.module.name) - \#(page.title) - +
diff --git a/Sources/swift-doc/Supporting Types/Page.swift b/Sources/swift-doc/Supporting Types/Page.swift index 3d13f5cf..14b20741 100644 --- a/Sources/swift-doc/Supporting Types/Page.swift +++ b/Sources/swift-doc/Supporting Types/Page.swift @@ -35,19 +35,27 @@ extension Page { } } +func route(for symbol: Symbol) -> String { + return route(for: symbol.id) +} + +func route(for name: CustomStringConvertible) -> String { + return name.description.replacingOccurrences(of: ".", with: "_") +} + func path(for symbol: Symbol, with baseURL: String) -> String { - return path(for: symbol.id.description, with: baseURL) + return path(for: route(for: symbol), with: baseURL) } func path(for identifier: CustomStringConvertible, with baseURL: String) -> String { var urlComponents = URLComponents(string: baseURL) - urlComponents?.path += "\(identifier)".replacingOccurrences(of: ".", with: "_") - guard let path = urlComponents?.string else { + urlComponents = urlComponents?.appendingPathComponent("\(identifier)") + guard let string = urlComponents?.string else { logger.critical("Unable to construct path for \(identifier) with baseURL \(baseURL)") fatalError() } - return path + return string } func writeFile(_ data: Data, to url: URL) throws { @@ -57,3 +65,16 @@ func writeFile(_ data: Data, to url: URL) throws { try data.write(to: url) try fileManager.setAttributes([.posixPermissions: 0o744], ofItemAtPath: url.path) } + +// MARK: - + +fileprivate extension URLComponents { + func appendingPathComponent(_ component: String) -> URLComponents? { + var urlComponents = self + var pathComponents = urlComponents.path.split(separator: "/").map { "\($0)" } + pathComponents.append(component) + urlComponents.path = "/" + pathComponents.joined(separator: "/") + + return urlComponents + } +}