Skip to content

Commit 1a57b92

Browse files
d-ronnqvistd-ronnqvist
authored
Deprecate and remove hierarchy information from linkable-elements.json (#1311)
* Deprecate hierarchy information from the link summaries. These link summaries are not meant to represent the documentation hierarchy and this task group information is too limited to work well. Clients who need this information should get it from the "link-hierarchy.json" file instead. * Remove task group information from the specification
1 parent b21d94f commit 1a57b92

File tree

7 files changed

+83
-288
lines changed

7 files changed

+83
-288
lines changed

‎Sources/SwiftDocC/Infrastructure/ConvertActionConverter.swift‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -150,7 +150,7 @@ package enum ConvertActionConverter {
150150
}
151151

152152
if emitDigest {
153-
let nodeLinkSummaries = entity.externallyLinkableElementSummaries(context: context, renderNode: renderNode, includeTaskGroups: true)
153+
let nodeLinkSummaries = entity.externallyLinkableElementSummaries(context: context, renderNode: renderNode)
154154
let nodeIndexingRecords = try renderNode.indexingRecords(onPage: identifier)
155155

156156
resultsGroup.async(queue: resultsSyncQueue) {
@@ -159,7 +159,7 @@ package enum ConvertActionConverter {
159159
indexingRecords.append(contentsOf: nodeIndexingRecords)
160160
}
161161
} else if FeatureFlags.current.isExperimentalLinkHierarchySerializationEnabled {
162-
let nodeLinkSummaries = entity.externallyLinkableElementSummaries(context: context, renderNode: renderNode, includeTaskGroups: false)
162+
let nodeLinkSummaries = entity.externallyLinkableElementSummaries(context: context, renderNode: renderNode)
163163

164164
resultsGroup.async(queue: resultsSyncQueue) {
165165
linkSummaries.append(contentsOf: nodeLinkSummaries)

‎Sources/SwiftDocC/LinkTargets/LinkDestinationSummary.swift‎

Lines changed: 75 additions & 48 deletions
Large diffs are not rendered by default.

‎Sources/SwiftDocC/SwiftDocC.docc/Resources/LinkableEntities.json‎

Lines changed: 1 addition & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
"openapi": "3.0.0",
33
"info": {
44
"description": "Specification of the DocC linkable-entities.json digest file.",
5-
"version": "0.3.0",
5+
"version": "0.3.1",
66
"title": "Linkable Entities"
77
},
88
"paths": { },
@@ -59,12 +59,6 @@
5959
"$ref": "#/components/schemas/PlatformAvailability"
6060
}
6161
},
62-
"taskGroups": {
63-
"type": "array",
64-
"items": {
65-
"$ref": "#/components/schemas/TaskGroup"
66-
}
67-
},
6862
"usr": {
6963
"type": "string"
7064
},
@@ -184,13 +178,6 @@
184178
"$ref": "#/components/schemas/DeclarationToken"
185179
},
186180
"nullable": true
187-
},
188-
"taskGroups": {
189-
"type": "array",
190-
"items": {
191-
"$ref": "#/components/schemas/TaskGroup"
192-
},
193-
"nullable": true
194181
}
195182
}
196183
},
@@ -517,23 +504,6 @@
517504
}
518505
}
519506
},
520-
"TaskGroup": {
521-
"type": "object",
522-
"required": [
523-
"identifiers"
524-
],
525-
"properties": {
526-
"title": {
527-
"type": "string"
528-
},
529-
"identifiers": {
530-
"type": "array",
531-
"items": {
532-
"type": "string"
533-
}
534-
}
535-
}
536-
},
537507
"DeclarationToken": {
538508
"required": [
539509
"text",

‎Tests/DocCCommandLineTests/ConvertActionTests.swift‎

Lines changed: 1 addition & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1003,11 +1003,6 @@ class ConvertActionTests: XCTestCase {
10031003
title: "TestBed",
10041004
language: .swift,
10051005
abstract: "TestBed abstract.",
1006-
taskGroups: [
1007-
.init(title: "Basics", identifiers: ["doc://com.test.example/documentation/TestBundle/Article"]),
1008-
.init(title: "Articles", identifiers: ["doc://com.test.example/documentation/TestBundle/SampleArticle"]),
1009-
.init(title: "Structures", identifiers: ["doc://com.test.example/documentation/TestBed/A"]),
1010-
],
10111006
usr: "TestBed",
10121007
availableLanguages: [.swift],
10131008
platforms: nil,
@@ -1025,7 +1020,6 @@ class ConvertActionTests: XCTestCase {
10251020
title: "A",
10261021
language: .swift,
10271022
abstract: "An abstract.",
1028-
taskGroups: [],
10291023
usr: "s:7TestBed1AV",
10301024
availableLanguages: [.swift],
10311025
platforms: nil,
@@ -1043,7 +1037,6 @@ class ConvertActionTests: XCTestCase {
10431037
title: "This is an article",
10441038
language: .swift,
10451039
abstract: "Article abstract.",
1046-
taskGroups: [],
10471040
availableLanguages: [.swift],
10481041
platforms: nil,
10491042
topicImages: nil,
@@ -1060,7 +1053,6 @@ class ConvertActionTests: XCTestCase {
10601053
title: "Sample Article",
10611054
language: .swift,
10621055
abstract: "Sample abstract.",
1063-
taskGroups: [],
10641056
availableLanguages: [.swift],
10651057
platforms: nil,
10661058
topicImages: nil,
@@ -1161,22 +1153,7 @@ class ConvertActionTests: XCTestCase {
11611153
}
11621154

11631155
// Rather than comparing all the linkable entities in the file, pull out one overload group
1164-
// and check its task groups
1165-
let overloadGroupEntity = try XCTUnwrap(resultLikableEntities.first(where: { $0.usr == "s:8ShapeKit18OverloadedProtocolP20fourthTestMemberName4testSdSS_tF::OverloadGroup" }))
1166-
1167-
let taskGroups = try XCTUnwrap(overloadGroupEntity.taskGroups)
1168-
guard taskGroups.count == 1, let overloadTaskGroup = taskGroups.first else {
1169-
XCTFail("Expected one task group, found \(taskGroups.count): \(taskGroups.map(\.title?.singleQuoted))")
1170-
return
1171-
}
1172-
1173-
XCTAssertEqual(overloadTaskGroup.title, "Overloads")
1174-
XCTAssertEqual(Set(overloadTaskGroup.identifiers), [
1175-
"doc://com.shapes.ShapeKit/documentation/ShapeKit/OverloadedProtocol/fourthTestMemberName(test:)-91hxs",
1176-
"doc://com.shapes.ShapeKit/documentation/ShapeKit/OverloadedProtocol/fourthTestMemberName(test:)-961zx",
1177-
"doc://com.shapes.ShapeKit/documentation/ShapeKit/OverloadedProtocol/fourthTestMemberName(test:)-8iuz7",
1178-
"doc://com.shapes.ShapeKit/documentation/ShapeKit/OverloadedProtocol/fourthTestMemberName(test:)-1h173",
1179-
])
1156+
XCTAssertTrue(resultLikableEntities.contains(where: { $0.usr == "s:8ShapeKit18OverloadedProtocolP20fourthTestMemberName4testSdSS_tF::OverloadGroup" }))
11801157
}
11811158

11821159
func testDownloadMetadataIsWrittenToOutputFolder() async throws {
@@ -1407,7 +1384,6 @@ class ConvertActionTests: XCTestCase {
14071384
title: "Making an Augmented Reality App",
14081385
language: .swift,
14091386
abstract: "This is an abstract for the intro.",
1410-
taskGroups: [.init(title: nil, identifiers: [reference.withFragment("Section-Name").absoluteString])],
14111387
availableLanguages: [.swift],
14121388
platforms: nil,
14131389
topicImages: nil,
@@ -1421,7 +1397,6 @@ class ConvertActionTests: XCTestCase {
14211397
title: "Section Name",
14221398
language: .swift,
14231399
abstract: nil,
1424-
taskGroups: [],
14251400
availableLanguages: [.swift],
14261401
platforms: nil,
14271402
topicImages: nil,
@@ -1438,7 +1413,6 @@ class ConvertActionTests: XCTestCase {
14381413
title: "Technology X",
14391414
language: .swift,
14401415
abstract: "Learn about some stuff in Technology X.",
1441-
taskGroups: [.init(title: nil, identifiers: [reference.appendingPath("Volume-1").absoluteString])],
14421416
availableLanguages: [.swift],
14431417
platforms: nil,
14441418
topicImages: nil,
@@ -3199,7 +3173,6 @@ private extension LinkDestinationSummary {
31993173
title: String,
32003174
language: SourceLanguage,
32013175
abstract: String?,
3202-
taskGroups: [TaskGroup],
32033176
usr: String? = nil,
32043177
availableLanguages: Set<SourceLanguage>,
32053178
platforms: [PlatformAvailability]?,
@@ -3216,7 +3189,6 @@ private extension LinkDestinationSummary {
32163189
abstract: abstract.map { [.text($0)] },
32173190
availableLanguages: availableLanguages,
32183191
platforms: platforms,
3219-
taskGroups: taskGroups,
32203192
usr: usr,
32213193
subheadingDeclarationFragments: nil,
32223194
redirects: redirects,

‎Tests/SwiftDocCTests/Infrastructure/DocumentationContext/DocumentationContextTests.swift‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5534,7 +5534,7 @@ let expected = """
55345534
let entity = try context.entity(with: reference)
55355535
let renderNode = try XCTUnwrap(converter.convert(entity))
55365536

5537-
return entity.externallyLinkableElementSummaries(context: context, renderNode: renderNode, includeTaskGroups: false)
5537+
return entity.externallyLinkableElementSummaries(context: context, renderNode: renderNode)
55385538
}
55395539
let linkResolutionInformation = try context.linkResolver.localResolver.prepareForSerialization(bundleID: context.inputs.id)
55405540

‎Tests/SwiftDocCTests/Infrastructure/ExternalPathHierarchyResolverTests.swift‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -713,7 +713,7 @@ class ExternalPathHierarchyResolverTests: XCTestCase {
713713
let entity = try dependencyContext.entity(with: reference)
714714
let renderNode = try XCTUnwrap(dependencyConverter.renderNode(for: entity))
715715

716-
return entity.externallyLinkableElementSummaries(context: dependencyContext, renderNode: renderNode, includeTaskGroups: false)
716+
return entity.externallyLinkableElementSummaries(context: dependencyContext, renderNode: renderNode)
717717
}
718718
let linkResolutionInformation = try dependencyContext.linkResolver.localResolver.prepareForSerialization(bundleID: dependencyContext.inputs.id)
719719

@@ -1004,7 +1004,7 @@ class ExternalPathHierarchyResolverTests: XCTestCase {
10041004
for reference in context.knownPages {
10051005
let node = try context.entity(with: reference)
10061006
let renderNode = converter.convert(node)
1007-
entitySummaries.append(contentsOf: node.externallyLinkableElementSummaries(context: context, renderNode: renderNode, includeTaskGroups: false))
1007+
entitySummaries.append(contentsOf: node.externallyLinkableElementSummaries(context: context, renderNode: renderNode))
10081008
}
10091009

10101010
let externalResolver = ExternalPathHierarchyResolver(

0 commit comments

Comments
 (0)