SwiftDocC: use "portable" paths for file names

compnerd · compnerd · commit 82bcf51b5f85 · 2023-07-24T14:42:51.000-07:00
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.
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/Infrastructure/DocumentationContext/DocumentationContextTests.swift b/Tests/SwiftDocCTests/Infrastructure/DocumentationContext/DocumentationContextTests.swift
@@ -474,7 +474,7 @@ class DocumentationContextTests: XCTestCase {
             Folder(name: "Resources", content: [
                 // This whitespace and punctuation in this *file name* will be replaced by dashes in its identifier.
                 // No content in this file result in identifiers.
-                TextFile(name: "Technology file: with - whitespace, and_punctuation.tutorial", utf8Content: """
+                TextFile(name: "Technology file_ with - whitespace, and_punctuation.tutorial", utf8Content: """
                 @Tutorials(name: "Technology Name") {
                    @Intro(title: "Intro Title") {
                       @Video(source: introvideo.mp4, poster: introposter.png)
@@ -510,10 +510,10 @@ class DocumentationContextTests: XCTestCase {
         let identifierPaths = context.knownIdentifiers.map { $0.path }.sorted(by: { lhs, rhs in lhs.count < rhs.count })
         XCTAssertEqual(identifierPaths, [
             // From the two file names
-            "/tutorials/Technology-file:-with---whitespace,-and_punctuation",
+            "/tutorials/Technology-file_-with---whitespace,-and_punctuation",
             // From the volume's title and the chapter's names, appended to their technology's identifier
-            "/tutorials/Technology-file:-with---whitespace,-and_punctuation/Volume_Section-Title:-with---various!-whitespace,-and/punctuation",
-            "/tutorials/Technology-file:-with---whitespace,-and_punctuation/Volume_Section-Title:-with---various!-whitespace,-and/punctuation/Chapter_Title:-with---various!-whitespace,-and/punctuation"
+            "/tutorials/Technology-file_-with---whitespace,-and_punctuation/Volume_Section-Title:-with---various!-whitespace,-and/punctuation",
+            "/tutorials/Technology-file_-with---whitespace,-and_punctuation/Volume_Section-Title:-with---various!-whitespace,-and/punctuation/Chapter_Title:-with---various!-whitespace,-and/punctuation"
         ])
     }
     
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"])

Original file line number	Diff line number	Diff line change
`@@ -96,7 +96,7 @@ final class RenderIndexTests: XCTestCase {`
`96`	`96`	`"type": "groupMarker"`
`97`	`97`	`},`
`98`	`98`	`{`
`99`		`- "path": "/documentation/mixedlanguageframework/bar/mystringfunction(_:)",`
	`99`	`+ "path": "/documentation/mixedlanguageframework/bar/mystringfunction(__)",`
`100`	`100`	`"title": "myStringFunction:error: (navigator title)",`
`101`	`101`	`"type": "method",`
`102`	`102`	`"children": [`
`@@ -324,7 +324,7 @@ final class RenderIndexTests: XCTestCase {`
`324`	`324`	`},`
`325`	`325`	`{`
`326`	`326`	`"title": "class func myStringFunction(String) throws -> String",`
`327`		`- "path": "/documentation/mixedlanguageframework/bar/mystringfunction(_:)",`
	`327`	`+ "path": "/documentation/mixedlanguageframework/bar/mystringfunction(__)",`
`328`	`328`	`"type": "method"`
`329`	`329`	`}`
`330`	`330`	`]`
`@@ -485,7 +485,7 @@ final class RenderIndexTests: XCTestCase {`
`485`	`485`	`"type": "groupMarker"`
`486`	`486`	`},`
`487`	`487`	`{`
`488`		`- "path": "\/documentation\/mixedlanguageframework\/foo-swift.struct\/init(rawvalue:)",`
	`488`	`+ "path": "\/documentation\/mixedlanguageframework\/foo-swift.struct\/init(rawvalue_)",`
`489`	`489`	`"title": "init(rawValue: UInt)",`
`490`	`490`	`"type": "init"`
`491`	`491`	`},`