Add an anchor to TaskGroupRenderSection (#883)

rdar://125967110 
rdar://124536381

Author: d-ronnqvist

Sources/SwiftDocC/Model/Rendering/RenderNodeTranslator.swift

@@ -996,7 +996,8 @@ public struct RenderNodeTranslator: SemanticVisitor {
                 abstract: nil,
                 discussion: nil,
                 identifiers: group.references.map(\.url.absoluteString),
-                generated: true
+                generated: true,
+                anchor: urlReadableFragment(group.title)
             )
         }
     }
@@ -1148,7 +1149,8 @@ public struct RenderNodeTranslator: SemanticVisitor {
                     default: break
                     }
                     return nil
-                }
+                },
+                anchor: group.heading.map { urlReadableFragment($0.plainText) } ?? "Topics"
             )
 
             // rdar://74617294 If a task group doesn't have any symbol or external links it shouldn't be rendered
@@ -1608,7 +1610,8 @@ public struct RenderNodeTranslator: SemanticVisitor {
                     title: group.heading,
                     abstract: nil,
                     discussion: nil,
-                    identifiers: group.references.map({ $0.url!.absoluteString })
+                    identifiers: group.references.map({ $0.url!.absoluteString }),
+                    anchor: urlReadableFragment(group.heading)
                 )
             }
         } ?? .init(defaultValue: [])

Sources/SwiftDocC/Model/Rendering/Symbol/TaskGroupRenderSection.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2021 Apple Inc. and the Swift project authors
+ Copyright (c) 2021-2024 Apple Inc. and the Swift project authors
  Licensed under Apache License v2.0 with Runtime Library Exception
 
  See https://swift.org/LICENSE.txt for license information
@@ -36,6 +36,8 @@ public struct TaskGroupRenderSection: RenderSection, Equatable {
     public let identifiers: [String]
     /// If true, this is an automatically generated group. If false, this is an authored group.
     public let generated: Bool
+    /// An optional anchor that can be used to link to the task group.
+    public let anchor: String?
 
     /// Creates a new task group.
     /// - Parameters:
@@ -44,17 +46,19 @@ public struct TaskGroupRenderSection: RenderSection, Equatable {
     ///   - discussion: An optional discussion for the section.
     ///   - identifiers: A list of topic-graph references.
     ///   - generated: If `true`, this is an automatically generated group. If `false`, this is an authored group.
-    public init(title: String?, abstract: [RenderInlineContent]?, discussion: RenderSection?, identifiers: [String], generated: Bool = false) {
+    ///   - anchor: An optional anchor that can be used to link to the task group.
+    public init(title: String?, abstract: [RenderInlineContent]?, discussion: RenderSection?, identifiers: [String], generated: Bool = false, anchor: String? = nil) {
         self.title = title
         self.abstract = abstract
         self.identifiers = identifiers
         self.generated = generated
+        self.anchor = anchor ?? title.map(urlReadableFragment)
         self.discussion = discussion
     }
 
     /// The list of keys you use to encode or decode this section.
     private enum CodingKeys: CodingKey {
-        case title, abstract, discussion, identifiers, generated
+        case title, abstract, discussion, identifiers, generated, anchor
     }
 
     public func encode(to encoder: Encoder) throws {
@@ -67,6 +71,7 @@ public struct TaskGroupRenderSection: RenderSection, Equatable {
         if generated {
             try container.encode(generated, forKey: .generated)
         }
+        try container.encodeIfPresent(anchor, forKey: .anchor)
     }
 
     public init(from decoder: Decoder) throws {
@@ -79,6 +84,7 @@ public struct TaskGroupRenderSection: RenderSection, Equatable {
         decoder.registerReferences(identifiers)
 
         generated = try container.decodeIfPresent(Bool.self, forKey: .generated) ?? false
+        anchor = try container.decodeIfPresent(String.self, forKey: .anchor)
         discussion = (try container.decodeIfPresent(CodableContentSection.self, forKey: .discussion)).map { $0.section }
     }
 }
@@ -91,6 +97,7 @@ extension TaskGroupRenderSection {
         self.abstract = nil
         self.identifiers = group.references.map({ $0.absoluteString })
         self.generated = true
+        self.anchor = group.title.map(urlReadableFragment)
         self.discussion = nil
     }
 }

Sources/SwiftDocC/SwiftDocC.docc/Resources/RenderNode.spec.json

@@ -2,7 +2,7 @@
     "openapi": "3.0.0",
     "info": {
         "description": "Render Node API",
-        "version": "0.4.1",
+        "version": "0.4.2",
         "title": "Render Node API"
     },
     "paths": { },
@@ -2704,6 +2704,9 @@
                     },
                     "generated": {
                         "type": "boolean"
+                    },
+                    "anchor": {
+                        "type": "string"
                     }
                 }
             },

Tests/SwiftDocCTests/Indexing/NavigatorIndexTests.swift

@@ -776,7 +776,8 @@ Root
                                                           abstract: section.abstract,
                                                           discussion: section.discussion,
                                                           identifiers: identifiers,
-                                                          generated: section.generated)
+                                                          generated: section.generated,
+                                                          anchor: section.title.map(urlReadableFragment))
                         }
                         return section
                     }

Tests/SwiftDocCTests/Infrastructure/DocumentationContext/DocumentationContextTests.swift

@@ -3100,7 +3100,7 @@ let expected = """
                 
                 ## Topics
                 
-                ### Some topic section
+                ### Some, topic - section!
                 
                 - <doc:Third>
                 """),
@@ -3176,6 +3176,22 @@ let expected = """
         let converter = DocumentationNodeConverter(bundle: bundle, context: context)
         let renderNode = try converter.convert(entity, at: nil)
 
+        XCTAssertEqual(renderNode.topicSections.map(\.anchor), [
+            "Another-topic-section"
+        ])
+        
+        let firstReference = try XCTUnwrap(context.knownPages.first(where: { $0.lastPathComponent == "First" }))
+        let firstRenderNode = try converter.convert(context.entity(with: firstReference), at: nil)
+        XCTAssertEqual(firstRenderNode.topicSections.map(\.anchor), [
+            "Topics"
+        ])
+        
+        let secondReference = try XCTUnwrap(context.knownPages.first(where: { $0.lastPathComponent == "Second" }))
+        let secondRenderNode = try converter.convert(context.entity(with: secondReference), at: nil)
+        XCTAssertEqual(secondRenderNode.topicSections.map(\.anchor), [
+            "Some-topic-section"
+        ])
+        
         let overviewSection = try XCTUnwrap(renderNode.primaryContentSections.first as? ContentRenderSection)
         guard case .unorderedList(let unorderedList) = overviewSection.content.dropFirst().first else {
             XCTFail("The first element of the Overview section (after the heading) should be an unordered list")

Tests/SwiftDocCTests/Model/RenderNodeDiffingBundleTests.swift

@@ -1,7 +1,7 @@
 /*
  This source file is part of the Swift.org open source project
 
- Copyright (c) 2023 Apple Inc. and the Swift project authors
+ Copyright (c) 2023-2024 Apple Inc. and the Swift project authors
  Licensed under Apache License v2.0 with Runtime Library Exception
 
  See https://swift.org/LICENSE.txt for license information
@@ -69,7 +69,8 @@ class RenderNodeDiffingBundleTests: XCTestCase {
                                                                                            discussion: nil,
                                                                                            identifiers: ["doc://org.swift.docc.example/tutorials/Test-Bundle/TestTutorial",
                                                                                                 "doc://org.swift.docc.example/tutorials/Test-Bundle/TestTutorial2"],
-                                                                                           generated: false)))
+                                                                                           generated: false,
+                                                                                           anchor: "Tutorials")))
         assertDifferences(differences,
                           contains: expectedDiff,
                           valueType: TaskGroupRenderSection.self)