Bugfix/relative links (#127)

* Fix relative link generation.

* Expose base-url argument for GitHub action.

* 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
```

* swap out path for absoluteString to ensure that both relative and absolute URLs are supported as documentation paths.

* Move path helper functions to SwiftDoc module

* Add PathTests

* Add assertions for function identifiers

See #134

* Add changelog entry for #127

Co-authored-by: Kare Morstol <[email protected]>
Co-authored-by: Mattt <[email protected]>

Author: 3 people

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
 

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
+}

Sources/swift-doc/Supporting Types/Layout.swift

@@ -1,3 +1,4 @@
+import SwiftDoc
 import HypertextLiteral
 import Foundation
 

Sources/swift-doc/Supporting Types/Page.swift

@@ -35,28 +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 {
-    var urlComponents = URLComponents(string: baseURL)
-    urlComponents = urlComponents?.appendingPathComponent("\(identifier)")
-    guard let string = urlComponents?.string 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
@@ -65,16 +44,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
-    }
-}

Tests/SwiftDocTests/PathTests.swift

@@ -0,0 +1,47 @@
+import XCTest
+
+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:)")
+    }
+}

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,