Add support for language specific topic sections (#755)

* Add support for language specific topic sections

rdar://118739654

* Allow SupportedLanguage anywhere in the topic section

Author: d-ronnqvist

Sources/SwiftDocC/Model/Rendering/RenderNodeTranslator.swift

@@ -1022,6 +1022,14 @@ public struct RenderNodeTranslator: SemanticVisitor {
         contentCompiler: inout RenderContentCompiler
     ) -> [TaskGroupRenderSection] {
         return topics.taskGroups.compactMap { group in
+            let supportedLanguages = Set(group.directives.compactMap {
+                SupportedLanguage(from: $0, source: nil, for: bundle, in: context)?.language
+            })
+            
+            // If the task group has a set of supported languages, see if it should render for the allowed traits.
+            guard supportedLanguages.isEmpty || supportedLanguages.matchesOneOf(traits: allowedTraits) else {
+                return nil
+            }
 
             let abstractContent = group.abstract.map {
                 return visitMarkup($0.content) as! [RenderInlineContent]
@@ -1969,3 +1977,16 @@ extension TutorialArticleSection: RenderTree {}
 extension ContentLayout: RenderTree {}
 
 extension ContentRenderSection: RenderTree {}
+
+private extension Set where Element == SourceLanguage {
+    func matchesOneOf(traits: Set<DocumentationDataVariantsTrait>) -> Bool {
+        traits.contains(where: {
+            guard let languageID = $0.interfaceLanguage,
+                  let traitLanguage = SourceLanguage(knownLanguageIdentifier: languageID)
+            else {
+                return false
+            }
+            return self.contains(traitLanguage)
+        })
+    }
+}

Sources/SwiftDocC/Model/TaskGroup.swift

@@ -187,7 +187,7 @@ public struct TaskGroup {
 
     /// An optional abstract for the task group.
     public var abstract: AbstractSection? {
-        if let firstParagraph = originalContent.first as? Paragraph {
+        if let firstParagraph = originalContent.mapFirst(where: { $0 as? Paragraph }) {
             return AbstractSection(paragraph: firstParagraph)
         }
         return nil
@@ -200,18 +200,15 @@ public struct TaskGroup {
             return nil
         }
 
-        let startIndex: Int
-        if originalContent.first is Paragraph {
-            startIndex = 1
-        } else {
-            startIndex = 0
-        }
+        var discussionChildren = originalContent
+            .prefix(while: { !($0 is UnorderedList) })
+            .filter({ !($0 is BlockDirective) })
 
-        let endIndex = originalContent.firstIndex(where: {
-            $0 is UnorderedList
-        }) ?? originalContent.endIndex
+        // Drop the abstract
+        if discussionChildren.first is Paragraph {
+            discussionChildren.removeFirst()
+        }
 
-        let discussionChildren = originalContent[startIndex..<endIndex]
         guard !discussionChildren.isEmpty else { return nil }
 
         return DiscussionSection(content: Array(discussionChildren))
@@ -225,6 +222,10 @@ public struct TaskGroup {
         self.heading = heading
         self.originalContent = content
     }
+    
+    var directives: [BlockDirective] {
+        originalContent.compactMap { $0 as? BlockDirective }
+    }
 }
 
 extension TaskGroup {

Tests/SwiftDocCTests/Model/SemaToRenderNodeTests.swift

@@ -3284,4 +3284,65 @@ Document
             ]
         )
     }
+    
+    func testLanguageSpecificTopicSections() throws {
+        let (_, bundle, context) = try testBundleAndContext(copying: "MixedLanguageFrameworkWithLanguageRefinements") { url in
+            try """
+            # ``MixedFramework/MyObjectiveCClassObjectiveCName``
+            
+            @Metadata {
+              @DocumentationExtension(mergeBehavior: override)
+            }
+            
+            Provide different curation in different languages
+            
+            ## Topics
+            
+            ### Something Swift only
+            
+            This link is only for Swift
+            
+            @SupportedLanguage(swift)
+            
+            - ``MyObjectiveCClassSwiftName/myMethodSwiftName()``
+            
+            ### Something Objective-C only
+                        
+            This link is only for Objective-C
+            
+            @SupportedLanguage(objc)
+            
+            - ``MyObjectiveCClassObjectiveCName/myMethodWithArgument:``
+            """.write(to: url.appendingPathComponent("MyObjectiveCClassObjectiveCName.md"), atomically: true, encoding: .utf8)
+        }
+        
+        XCTAssert(context.problems.isEmpty, "\(context.problems.map(\.diagnostic.summary))")
+        
+        let reference = try XCTUnwrap(context.knownIdentifiers.first { $0.path.hasSuffix("MixedFramework/MyObjectiveCClassSwiftName") })
+        
+        let documentationNode = try context.entity(with: reference)
+        XCTAssertEqual(documentationNode.availableVariantTraits.count, 2, "This page has Swift and Objective-C variants")
+        
+        let converter = DocumentationNodeConverter(bundle: bundle, context: context)
+        let renderNode = try converter.convert(documentationNode, at: nil)
+        
+        let topicSectionsVariants = renderNode.topicSectionsVariants
+        
+        let swiftTopicSection = topicSectionsVariants.defaultValue
+        
+        XCTAssertEqual(swiftTopicSection.first?.title, "Something Swift only")
+        XCTAssertEqual(swiftTopicSection.first?.abstract?.plainText, "This link is only for Swift")
+        XCTAssertEqual(swiftTopicSection.first?.identifiers, [
+            "doc://org.swift.MixedFramework/documentation/MixedFramework/MyObjectiveCClassSwiftName/myMethodSwiftName()"
+        ])
+        
+        let objcTopicSectionVariant = try XCTUnwrap(topicSectionsVariants.variants.first { $0.traits[0] == .interfaceLanguage("occ") })
+        let objcTopicSection = objcTopicSectionVariant.applyingPatchTo(swiftTopicSection)
+        
+        XCTAssertEqual(objcTopicSection.first?.title, "Something Objective-C only")
+        XCTAssertEqual(objcTopicSection.first?.abstract?.plainText, "This link is only for Objective-C")
+        XCTAssertEqual(objcTopicSection.first?.identifiers, [
+            "doc://org.swift.MixedFramework/documentation/MixedFramework/MyObjectiveCClassSwiftName/myMethod(argument:)"
+        ])
+    }
 }

Tests/SwiftDocCTests/Model/TaskGroupTests.swift

@@ -221,4 +221,204 @@ class TaskGroupTests: XCTestCase {
             XCTAssertEqual("https://www.example.com", links[1].destination)
         }
     }
+    
+    func testSupportedLanguages() throws {
+        let markupSource = """
+            # Title
+            
+            Abstract.
+            
+            ## Topics
+            
+            ### Something Swift only
+            
+            This link is only for Swift
+            
+            @SupportedLanguage(swift)
+            
+            - ``Link1``
+            
+            ### Something Objective-C only
+                        
+            This link is only for Objective-C
+            
+            @SupportedLanguage(objc)
+            
+            - ``Link1``
+            
+            ### Something for both
+                        
+            This link is for both Swift and Objective-C
+            
+            @SupportedLanguage(objc)
+            @SupportedLanguage(swift)
+            
+            - ``Link3``
+                            
+            ### Something without a language filter
+                        
+            This link is for all languages
+            
+            - ``Link4``
+            """
+        let document = Document(parsing: markupSource, options: [.parseBlockDirectives, .parseSymbolLinks])
+        let markupModel = DocumentationMarkup(markup: document)
+        
+        XCTAssertEqual("Abstract.", Paragraph(markupModel.abstractSection?.content.compactMap { $0 as? InlineMarkup } ?? []).detachedFromParent.format())
+        
+        let topicSection = try XCTUnwrap(markupModel.topicsSection)
+        XCTAssertEqual(topicSection.taskGroups.count, 4)
+        
+        do {
+            let taskGroup = try XCTUnwrap(topicSection.taskGroups.first)
+            XCTAssertEqual(taskGroup.heading?.detachedFromParent.format(), "### Something Swift only")
+            XCTAssertEqual(taskGroup.abstract?.paragraph.detachedFromParent.format(), "This link is only for Swift")
+            XCTAssertEqual(taskGroup.directives.count, 1)
+            for directive in taskGroup.directives {
+                XCTAssertEqual(directive.name, "SupportedLanguage")
+                XCTAssertEqual(directive.arguments().count, 1)
+            }
+            XCTAssertEqual(taskGroup.links.count, 1)
+        }
+        
+        do {
+            let taskGroup = try XCTUnwrap(topicSection.taskGroups.dropFirst().first)
+            XCTAssertEqual(taskGroup.heading?.detachedFromParent.format(), "### Something Objective-C only")
+            XCTAssertEqual(taskGroup.abstract?.paragraph.detachedFromParent.format(), "This link is only for Objective-C")
+            XCTAssertEqual(taskGroup.directives.count, 1)
+            for directive in taskGroup.directives {
+                XCTAssertEqual(directive.name, "SupportedLanguage")
+                XCTAssertEqual(directive.arguments().count, 1)
+            }
+            XCTAssertEqual(taskGroup.links.count, 1)
+        }
+        
+        do {
+            let taskGroup = try XCTUnwrap(topicSection.taskGroups.dropFirst(2).first)
+            XCTAssertEqual(taskGroup.heading?.detachedFromParent.format(), "### Something for both")
+            XCTAssertEqual(taskGroup.abstract?.paragraph.detachedFromParent.format(), "This link is for both Swift and Objective-C")
+            XCTAssertEqual(taskGroup.directives.count, 2)
+            for directive in taskGroup.directives {
+                XCTAssertEqual(directive.name, "SupportedLanguage")
+                XCTAssertEqual(directive.arguments().count, 1)
+            }
+            XCTAssertEqual(taskGroup.links.count, 1)
+        }
+        
+        do {
+            let taskGroup = try XCTUnwrap(topicSection.taskGroups.dropFirst(3).first)
+            XCTAssertEqual(taskGroup.heading?.detachedFromParent.format(), "### Something without a language filter")
+            XCTAssertEqual(taskGroup.abstract?.paragraph.detachedFromParent.format(), "This link is for all languages")
+            XCTAssert(taskGroup.directives.isEmpty)
+            XCTAssertEqual(taskGroup.links.count, 1)
+        }
+    }
+    
+    func testTopicContentOrder() throws {
+        func assertExpectedParsedTaskGroupContent(_ content: String, file: StaticString = #file, line: UInt = #line) throws {
+            let document = Document(parsing: """
+                # Title
+                
+                Abstract.
+                
+                ## Topics
+                
+                \(content)
+                
+                """, options: [.parseBlockDirectives, .parseSymbolLinks])
+            let markupModel = DocumentationMarkup(markup: document)
+            
+            let topicSection = try XCTUnwrap(markupModel.topicsSection, file: file, line: line)
+            XCTAssertEqual(topicSection.taskGroups.count, 1, file: file, line: line)
+            
+            let taskGroup = try XCTUnwrap(topicSection.taskGroups.first, file: file, line: line)
+            
+            XCTAssertEqual(taskGroup.heading?.title, "Topic name", file: file, line: line)
+            XCTAssertEqual(taskGroup.abstract?.paragraph.detachedFromParent.format(), "Abstract paragraph", file: file, line: line)
+            XCTAssertEqual(taskGroup.discussion?.content.map { $0.detachedFromParent.format() }, [
+                "Discussion paragraph 1",
+                "Discussion paragraph 2",
+            ], file: file, line: line)
+            XCTAssertEqual(taskGroup.directives.count, 1, file: file, line: line)
+            XCTAssertEqual(taskGroup.directives.first?.name, "SupportedLanguage", file: file, line: line)
+            XCTAssertEqual(taskGroup.directives.first?.arguments().count, 1, file: file, line: line)
+            XCTAssertEqual(taskGroup.links.map(\.destination), ["Link1", "Link2"], file: file, line: line)
+        }
+        
+        try assertExpectedParsedTaskGroupContent("""
+            ### Topic name
+            
+            Abstract paragraph
+            
+            Discussion paragraph 1
+            
+            Discussion paragraph 2
+            
+            @SupportedLanguage(swift)
+            
+            - ``Link1``
+            - ``Link2``
+            """)
+        
+        try assertExpectedParsedTaskGroupContent("""
+            ### Topic name
+            
+            Abstract paragraph
+            
+            @SupportedLanguage(swift)
+            
+            Discussion paragraph 1
+            
+            Discussion paragraph 2
+            
+            - ``Link1``
+            - ``Link2``
+            """)
+        
+        try assertExpectedParsedTaskGroupContent("""
+            ### Topic name
+            
+            @SupportedLanguage(swift)
+            
+            Abstract paragraph
+            
+            Discussion paragraph 1
+            
+            Discussion paragraph 2
+            
+            - ``Link1``
+            - ``Link2``
+            """)
+        
+        try assertExpectedParsedTaskGroupContent("""
+            ### Topic name
+            
+            Abstract paragraph
+            
+            Discussion paragraph 1
+            
+            @SupportedLanguage(swift)
+            
+            Discussion paragraph 2
+            
+            - ``Link1``
+            - ``Link2``
+            """)
+        
+        try assertExpectedParsedTaskGroupContent("""
+            ### Topic name
+            
+            Abstract paragraph
+            
+            Discussion paragraph 1
+            
+            Discussion paragraph 2
+            
+            - ``Link1``
+            - ``Link2``
+            
+            @SupportedLanguage(swift)
+            """)
+        
+    }
 }