From b9b37e4335095c5deab39f64cdb6204eed777eb0 Mon Sep 17 00:00:00 2001 From: Mathew Polzin Date: Sat, 23 May 2020 19:19:29 -0700 Subject: [PATCH 1/8] Fix relative link generation. --- Sources/swift-doc/Supporting Types/Page.swift | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/Sources/swift-doc/Supporting Types/Page.swift b/Sources/swift-doc/Supporting Types/Page.swift index 14b20741..13a7794f 100644 --- a/Sources/swift-doc/Supporting Types/Page.swift +++ b/Sources/swift-doc/Supporting Types/Page.swift @@ -70,11 +70,7 @@ func writeFile(_ data: Data, to url: URL) throws { 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 + return url.map { $0.appendingPathComponent(component) } + .flatMap { URLComponents(url: $0, resolvingAgainstBaseURL: true) } } } From 32124df8250961d3a54a61257136f397e84c68bf Mon Sep 17 00:00:00 2001 From: Mathew Polzin Date: Sat, 23 May 2020 19:25:14 -0700 Subject: [PATCH 2/8] Expose base-url argument for GitHub action. --- action.yml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/action.yml b/action.yml index e49b486b..c0ad7287 100644 --- a/action.yml +++ b/action.yml @@ -12,6 +12,10 @@ inputs: format: description: "The output format (commonmark or html)" default: "commonmark" + base-url: + description: "The base URL for all relative URLs generated in documents" + required: false + default: "./" output: description: "The path for generated output" required: true @@ -26,6 +30,8 @@ runs: "${{ inputs.inputs }}", --format, "${{ inputs.format }}", + --base-url, + "${{ inputs.base-url }}", --module-name, "${{ inputs.module-name }}", --output, From 17edb2cb6c370676469b37b2cae73376469f0c3b Mon Sep 17 00:00:00 2001 From: Kare Morstol Date: Wed, 1 Jul 2020 15:49:56 +0200 Subject: [PATCH 3/8] fix #134: crash for operator functions when no baseURL. Fixes crashes like this one: ```bash $ swift doc generate my-repo/Sources --module-name MyRepo 2020-06-30T17:00:13-0400 critical: Unable to construct path for /(lhs:rhs:) with baseURL / Fatal error: file /private/tmp/swift-doc-20200630-24417-jrxtfw/Sources/swift-doc/Supporting Types/Page.swift, line 55 zsh: illegal hardware instruction swift doc generate my-repo/Sources --module-name MyRepo ``` --- Sources/swift-doc/Supporting Types/Page.swift | 18 ++---------------- 1 file changed, 2 insertions(+), 16 deletions(-) diff --git a/Sources/swift-doc/Supporting Types/Page.swift b/Sources/swift-doc/Supporting Types/Page.swift index 14b20741..9f0dc031 100644 --- a/Sources/swift-doc/Supporting Types/Page.swift +++ b/Sources/swift-doc/Supporting Types/Page.swift @@ -48,9 +48,8 @@ func path(for symbol: Symbol, with baseURL: String) -> String { } func path(for identifier: CustomStringConvertible, with baseURL: String) -> String { - var urlComponents = URLComponents(string: baseURL) - urlComponents = urlComponents?.appendingPathComponent("\(identifier)") - guard let string = urlComponents?.string else { + let url = URL(string: baseURL)?.appendingPathComponent("\(identifier)") + guard let string = url?.path else { logger.critical("Unable to construct path for \(identifier) with baseURL \(baseURL)") fatalError() } @@ -65,16 +64,3 @@ 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 - } -} From 33d062837176b3a11bf1098c0e2c3dbf2b7d5767 Mon Sep 17 00:00:00 2001 From: Mathew Polzin Date: Fri, 24 Jul 2020 19:57:53 -0700 Subject: [PATCH 4/8] swap out path for absoluteString to ensure that both relative and absolute URLs are supported as documentation paths. --- Sources/swift-doc/Supporting Types/Page.swift | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Sources/swift-doc/Supporting Types/Page.swift b/Sources/swift-doc/Supporting Types/Page.swift index 9f0dc031..d8c179c7 100644 --- a/Sources/swift-doc/Supporting Types/Page.swift +++ b/Sources/swift-doc/Supporting Types/Page.swift @@ -49,7 +49,7 @@ func path(for symbol: Symbol, with baseURL: String) -> String { func path(for identifier: CustomStringConvertible, with baseURL: String) -> String { let url = URL(string: baseURL)?.appendingPathComponent("\(identifier)") - guard let string = url?.path else { + guard let string = url?.absoluteString else { logger.critical("Unable to construct path for \(identifier) with baseURL \(baseURL)") fatalError() } From 58086d48c85c56c67b65a26f12e5265c59195b86 Mon Sep 17 00:00:00 2001 From: Mattt Date: Mon, 27 Jul 2020 07:51:44 -0700 Subject: [PATCH 5/8] Move path helper functions to SwiftDoc module --- Sources/SwiftDoc/Helpers.swift | 22 +++++++++++++++++++ .../swift-doc/Supporting Types/Layout.swift | 1 + Sources/swift-doc/Supporting Types/Page.swift | 20 ----------------- 3 files changed, 23 insertions(+), 20 deletions(-) create mode 100644 Sources/SwiftDoc/Helpers.swift diff --git a/Sources/SwiftDoc/Helpers.swift b/Sources/SwiftDoc/Helpers.swift new file mode 100644 index 00000000..7a19bb28 --- /dev/null +++ b/Sources/SwiftDoc/Helpers.swift @@ -0,0 +1,22 @@ +import Foundation + +public func route(for symbol: Symbol) -> String { + return route(for: symbol.id) +} + +public func route(for name: CustomStringConvertible) -> String { + return name.description.replacingOccurrences(of: ".", with: "_") +} + +public func path(for symbol: Symbol, with baseURL: String) -> String { + return path(for: route(for: symbol), with: baseURL) +} + +public func path(for identifier: CustomStringConvertible, with baseURL: String) -> String { + let url = URL(string: baseURL)?.appendingPathComponent("\(identifier)") ?? URL(string: "\(identifier)") + guard let string = url?.absoluteString else { + fatalError("Unable to construct path for \(identifier) with baseURL \(baseURL)") + } + + return string +} diff --git a/Sources/swift-doc/Supporting Types/Layout.swift b/Sources/swift-doc/Supporting Types/Layout.swift index a9c940f2..16429c4f 100644 --- a/Sources/swift-doc/Supporting Types/Layout.swift +++ b/Sources/swift-doc/Supporting Types/Layout.swift @@ -1,3 +1,4 @@ +import SwiftDoc import HypertextLiteral import Foundation diff --git a/Sources/swift-doc/Supporting Types/Page.swift b/Sources/swift-doc/Supporting Types/Page.swift index d8c179c7..ece11da3 100644 --- a/Sources/swift-doc/Supporting Types/Page.swift +++ b/Sources/swift-doc/Supporting Types/Page.swift @@ -35,27 +35,7 @@ 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: route(for: symbol), with: baseURL) -} - -func path(for identifier: CustomStringConvertible, with baseURL: String) -> String { - let url = URL(string: baseURL)?.appendingPathComponent("\(identifier)") - guard let string = url?.absoluteString else { - logger.critical("Unable to construct path for \(identifier) with baseURL \(baseURL)") - fatalError() - } - - return string -} func writeFile(_ data: Data, to url: URL) throws { let fileManager = FileManager.default From f6b1e748159306d403fcfe80cbf1fec2099fb269 Mon Sep 17 00:00:00 2001 From: Mattt Date: Mon, 27 Jul 2020 07:51:51 -0700 Subject: [PATCH 6/8] Add PathTests --- Tests/SwiftDocTests/PathTests.swift | 32 +++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 Tests/SwiftDocTests/PathTests.swift diff --git a/Tests/SwiftDocTests/PathTests.swift b/Tests/SwiftDocTests/PathTests.swift new file mode 100644 index 00000000..9a9cc7f7 --- /dev/null +++ b/Tests/SwiftDocTests/PathTests.swift @@ -0,0 +1,32 @@ +import XCTest + +import SwiftDoc + +final class PathTests: XCTestCase { + func testEmptyBaseURL() { + XCTAssertEqual(path(for: "Class", with: ""), "Class") + } + + func testRootDirectoryBaseURL() { + XCTAssertEqual(path(for: "Class", with: "/"), "/Class") + } + + func testCurrentDirectoryBaseURL() { + XCTAssertEqual(path(for: "Class", with: "./"), "./Class") + } + + func testNestedSubdirectoryBaseURL() { + XCTAssertEqual(path(for: "Class", with: "/path/to/directory"), "/path/to/directory/Class") + XCTAssertEqual(path(for: "Class", with: "/path/to/directory/"), "/path/to/directory/Class") + } + + func testDomainBaseURL() { + XCTAssertEqual(path(for: "Class", with: "https://example.com"), "https://example.com/Class") + XCTAssertEqual(path(for: "Class", with: "https://example.com/"), "https://example.com/Class") + } + + func testDomainSubdirectoryBaseURL() { + XCTAssertEqual(path(for: "Class", with: "https://example.com/docs"), "https://example.com/docs/Class") + XCTAssertEqual(path(for: "Class", with: "https://example.com/docs/"), "https://example.com/docs/Class") + } +} From 4f7bf94486adaae400a9f8c0d3a11e4b5b1e0c19 Mon Sep 17 00:00:00 2001 From: Mattt Date: Mon, 27 Jul 2020 08:01:16 -0700 Subject: [PATCH 7/8] Add assertions for function identifiers See #134 --- Tests/SwiftDocTests/PathTests.swift | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/Tests/SwiftDocTests/PathTests.swift b/Tests/SwiftDocTests/PathTests.swift index 9a9cc7f7..a33804d7 100644 --- a/Tests/SwiftDocTests/PathTests.swift +++ b/Tests/SwiftDocTests/PathTests.swift @@ -5,28 +5,43 @@ import SwiftDoc final class PathTests: XCTestCase { func testEmptyBaseURL() { XCTAssertEqual(path(for: "Class", with: ""), "Class") + + XCTAssertEqual(path(for: "(lhs:rhs:)", with: ""), "(lhs:rhs:)") } func testRootDirectoryBaseURL() { XCTAssertEqual(path(for: "Class", with: "/"), "/Class") + + XCTAssertEqual(path(for: "(lhs:rhs:)", with: "/"), "/(lhs:rhs:)") } func testCurrentDirectoryBaseURL() { XCTAssertEqual(path(for: "Class", with: "./"), "./Class") + + XCTAssertEqual(path(for: "(lhs:rhs:)", with: "./"), "./(lhs:rhs:)") } func testNestedSubdirectoryBaseURL() { XCTAssertEqual(path(for: "Class", with: "/path/to/directory"), "/path/to/directory/Class") XCTAssertEqual(path(for: "Class", with: "/path/to/directory/"), "/path/to/directory/Class") + + XCTAssertEqual(path(for: "(lhs:rhs:)", with: "/path/to/directory"), "/path/to/directory/(lhs:rhs:)") + XCTAssertEqual(path(for: "(lhs:rhs:)", with: "/path/to/directory/"), "/path/to/directory/(lhs:rhs:)") } func testDomainBaseURL() { XCTAssertEqual(path(for: "Class", with: "https://example.com"), "https://example.com/Class") XCTAssertEqual(path(for: "Class", with: "https://example.com/"), "https://example.com/Class") + + XCTAssertEqual(path(for: "(lhs:rhs:)", with: "https://example.com"), "https://example.com/(lhs:rhs:)") + XCTAssertEqual(path(for: "(lhs:rhs:)", with: "https://example.com/"), "https://example.com/(lhs:rhs:)") } func testDomainSubdirectoryBaseURL() { XCTAssertEqual(path(for: "Class", with: "https://example.com/docs"), "https://example.com/docs/Class") XCTAssertEqual(path(for: "Class", with: "https://example.com/docs/"), "https://example.com/docs/Class") + + XCTAssertEqual(path(for: "(lhs:rhs:)", with: "https://example.com/docs"), "https://example.com/docs/(lhs:rhs:)") + XCTAssertEqual(path(for: "(lhs:rhs:)", with: "https://example.com/docs/"), "https://example.com/docs/(lhs:rhs:)") } } From f8cc4e3d405018ccfdfdbce080e64dde4e0e5c9f Mon Sep 17 00:00:00 2001 From: Mattt Date: Mon, 27 Jul 2020 08:01:25 -0700 Subject: [PATCH 8/8] Add changelog entry for #127 --- Changelog.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/Changelog.md b/Changelog.md index 683f59c1..7592a883 100644 --- a/Changelog.md +++ b/Changelog.md @@ -13,6 +13,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 #140 by @JaapWijnen. - Fixed whitespace of code listings. #144 by @mbrandonw. +- Fixed crash when attempting to generate paths with no base URL specified. + #127 by @mattpolzin, @kareman, and @mattt. ## [1.0.0-beta.3] - 2020-05-19