Skip to content

Commit

Permalink
SwiftDocC: use "portable" paths for file names
Browse files Browse the repository at this point in the history
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.
  • Loading branch information
compnerd committed May 9, 2024
1 parent e824c42 commit 74fbe3f
Show file tree
Hide file tree
Showing 7 changed files with 20 additions and 14 deletions.
8 changes: 7 additions & 1 deletion Sources/SwiftDocC/Infrastructure/NodeURLGenerator.swift
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand Down
2 changes: 1 addition & 1 deletion Tests/SwiftDocCTests/Indexing/NavigatorIndexTests.swift
Original file line number Diff line number Diff line change
Expand Up @@ -891,7 +891,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)
Expand Down
6 changes: 3 additions & 3 deletions Tests/SwiftDocCTests/Indexing/RenderIndexTests.swift
Original file line number Diff line number Diff line change
Expand Up @@ -99,7 +99,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": [
Expand Down Expand Up @@ -327,7 +327,7 @@ final class RenderIndexTests: XCTestCase {
},
{
"title": "class func myStringFunction(String) throws -> String",
"path": "/documentation/mixedlanguageframework/bar/mystringfunction(_:)",
"path": "/documentation/mixedlanguageframework/bar/mystringfunction(__)",
"type": "method"
}
]
Expand Down Expand Up @@ -488,7 +488,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"
},
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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"
])
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -287,7 +287,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)
Expand Down Expand Up @@ -508,7 +508,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)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -614,7 +614,7 @@
"type" : "groupMarker"
},
{
"path" : "\/documentation\/mykit\/globalfunction(_:considering:)",
"path" : "\/documentation\/mykit\/globalfunction(__considering_)",
"title" : "func globalFunction(Data, considering: Int)",
"type" : "func"
},
Expand All @@ -638,7 +638,7 @@
"type" : "groupMarker"
},
{
"path" : "\/documentation\/sidekit\/sideclass\/value(_:)",
"path" : "\/documentation\/sidekit\/sideclass\/value(__)",
"title" : "case Value(Int)",
"type" : "case"
},
Expand Down
2 changes: 1 addition & 1 deletion Tests/SwiftDocCUtilitiesTests/ConvertActionTests.swift
Original file line number Diff line number Diff line change
Expand Up @@ -330,7 +330,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"])
Expand Down

0 comments on commit 74fbe3f

Please sign in to comment.