SwiftDocC: use "portable" paths for file names

Windows restricts a CharacterSet from use in the file name. Replace that set with `_`. This requires an associated change in the DocC renderer to perform the substitution when converting the URL to a file path.
apple · Jul 22, 2023 · 6b10dbf · 6b10dbf
1 parent a85c614
commit 6b10dbf
Show file tree

Hide file tree

Showing 6 changed files with 16 additions and 10 deletions.
diff --git a/Sources/SwiftDocC/Infrastructure/NodeURLGenerator.swift b/Sources/SwiftDocC/Infrastructure/NodeURLGenerator.swift
@@ -194,7 +194,13 @@ public struct NodeURLGenerator {
  isURLModified = true
  name = "'\(name)"
  }
-
+
+ let components = name.components(separatedBy: ["<", ">", ":", "\"", "/", "\\", "|", "?", "*"])
+ if components.count > 1 {
+ isURLModified = true
+ name = components.joined(separator: "_")
+ }
+
  // Shorten path components that are too long.
  // Take the first 240 chars and append a checksum on the *complete* string.
  if name.count >= pathComponentLengthLimit {

diff --git a/Tests/SwiftDocCTests/Indexing/NavigatorIndexTests.swift b/Tests/SwiftDocCTests/Indexing/NavigatorIndexTests.swift
@@ -706,7 +706,7 @@ Root
  XCTAssertEqual(navigatorIndex.path(for: 4), "/tutorials/testoverview")
  XCTAssertEqual(navigatorIndex.path(for: 9), "/documentation/fillintroduced/maccatalystonlydeprecated()")
  XCTAssertEqual(navigatorIndex.path(for: 10), "/documentation/fillintroduced/maccatalystonlyintroduced()")
- XCTAssertEqual(navigatorIndex.path(for: 21), "/documentation/mykit/globalfunction(_:considering:)")
+ XCTAssertEqual(navigatorIndex.path(for: 21), "/documentation/mykit/globalfunction(__considering_)")
  XCTAssertEqual(navigatorIndex.path(for: 23), "/documentation/sidekit/uncuratedclass/angle")
 
  assertUniqueIDs(node: navigatorIndex.navigatorTree.root)

diff --git a/Tests/SwiftDocCTests/Indexing/RenderIndexTests.swift b/Tests/SwiftDocCTests/Indexing/RenderIndexTests.swift
@@ -96,7 +96,7 @@ final class RenderIndexTests: XCTestCase {
  "type": "groupMarker"
  },
  {
- "path": "/documentation/mixedlanguageframework/bar/mystringfunction(_:)",
+ "path": "/documentation/mixedlanguageframework/bar/mystringfunction(__)",
  "title": "myStringFunction:error: (navigator title)",
  "type": "method",
  "children": [
@@ -324,7 +324,7 @@ final class RenderIndexTests: XCTestCase {
  },
  {
  "title": "class func myStringFunction(String) throws -> String",
- "path": "/documentation/mixedlanguageframework/bar/mystringfunction(_:)",
+ "path": "/documentation/mixedlanguageframework/bar/mystringfunction(__)",
  "type": "method"
  }
  ]
@@ -485,7 +485,7 @@ final class RenderIndexTests: XCTestCase {
  "type": "groupMarker"
  },
  {
- "path": "\/documentation\/mixedlanguageframework\/foo-swift.struct\/init(rawvalue:)",
+ "path": "\/documentation\/mixedlanguageframework\/foo-swift.struct\/init(rawvalue_)",
  "title": "init(rawValue: UInt)",
  "type": "init"
  },

diff --git a/Tests/SwiftDocCTests/LinkTargets/LinkDestinationSummaryTests.swift b/Tests/SwiftDocCTests/LinkTargets/LinkDestinationSummaryTests.swift
@@ -276,7 +276,7 @@ class ExternalLinkableTests: XCTestCase {
  let summary = node.externallyLinkableElementSummaries(context: context, renderNode: renderNode)[0]
 
  XCTAssertEqual(summary.title, "globalFunction(_:considering:)")
- XCTAssertEqual(summary.relativePresentationURL.absoluteString, "/documentation/mykit/globalfunction(_:considering:)")
+ XCTAssertEqual(summary.relativePresentationURL.absoluteString, "/documentation/mykit/globalfunction(__considering_)")
  XCTAssertEqual(summary.referenceURL.absoluteString, "doc://org.swift.docc.example/documentation/MyKit/globalFunction(_:considering:)")
  XCTAssertEqual(summary.language, .swift)
  XCTAssertEqual(summary.kind, .function)
@@ -486,7 +486,7 @@ class ExternalLinkableTests: XCTestCase {
  let summary = node.externallyLinkableElementSummaries(context: context, renderNode: renderNode)[0]
 
  XCTAssertEqual(summary.title, "myStringFunction(_:)")
- XCTAssertEqual(summary.relativePresentationURL.absoluteString, "/documentation/mixedlanguageframework/bar/mystringfunction(_:)")
+ XCTAssertEqual(summary.relativePresentationURL.absoluteString, "/documentation/mixedlanguageframework/bar/mystringfunction(__)")
  XCTAssertEqual(summary.referenceURL.absoluteString, "doc://org.swift.MixedLanguageFramework/documentation/MixedLanguageFramework/Bar/myStringFunction(_:)")
  XCTAssertEqual(summary.language, .swift)
  XCTAssertEqual(summary.kind, .typeMethod)

diff --git a/Tests/SwiftDocCTests/Test Resources/TestBundle-RenderIndex.json b/Tests/SwiftDocCTests/Test Resources/TestBundle-RenderIndex.json
@@ -614,7 +614,7 @@
  "type" : "groupMarker"
  },
  {
- "path" : "\/documentation\/mykit\/globalfunction(_:considering:)",
+ "path" : "\/documentation\/mykit\/globalfunction(__considering_)",
  "title" : "func globalFunction(Data, considering: Int)",
  "type" : "func"
  },
@@ -638,7 +638,7 @@
  "type" : "groupMarker"
  },
  {
- "path" : "\/documentation\/sidekit\/sideclass\/value(_:)",
+ "path" : "\/documentation\/sidekit\/sideclass\/value(__)",
  "title" : "case Value(Int)",
  "type" : "case"
  },

diff --git a/Tests/SwiftDocCUtilitiesTests/ConvertActionTests.swift b/Tests/SwiftDocCUtilitiesTests/ConvertActionTests.swift
@@ -324,7 +324,7 @@ class ConvertActionTests: XCTestCase {
  "/output/data/documentation/mykit/myclass/init()-3743d.json",
  "/output/data/documentation/mykit/myclass/myfunction().json",
  "/output/data/documentation/mykit/myprotocol.json",
- "/output/data/documentation/mykit/globalfunction(_:considering:).json",
+ "/output/data/documentation/mykit/globalfunction(__considering_).json",
  ].sorted())
 
  let myKitNodeData = try XCTUnwrap(outputData["/output/data/documentation/mykit.json"])