Add a helper function for rendering a Topics/SeeAlso section as HTML #1382
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,152 @@ | ||||||
| /* | ||||||
| This source file is part of the Swift.org open source project | ||||||
|
|
||||||
| Copyright (c) 2025 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 | ||||||
| See https://swift.org/CONTRIBUTORS.txt for Swift project authors | ||||||
| */ | ||||||
|
|
||||||
| #if canImport(FoundationXML) | ||||||
| // TODO: Consider other HTML rendering options as a future improvement (rdar://165755530) | ||||||
| package import FoundationXML | ||||||
| package import FoundationEssentials | ||||||
| #else | ||||||
| package import Foundation | ||||||
| #endif | ||||||
|
|
||||||
| package import Markdown | ||||||
| package import DocCCommon | ||||||
|
|
||||||
| package extension MarkdownRenderer { | ||||||
| /// Information about a task group that organizes other API into a hierarchy on this page. | ||||||
| struct TaskGroupInfo { | ||||||
| /// The title of this group of API | ||||||
| package var title: String? | ||||||
| /// Any additional free-form content that describes the group of API. | ||||||
| package var content: [any Markup] | ||||||
| /// A list of already resolved references that the renderer should display, in order, for this group. | ||||||
| package var references: [URL] | ||||||
|
|
||||||
| package init(title: String?, content: [any Markup], references: [URL]) { | ||||||
| self.title = title | ||||||
| self.content = content | ||||||
| self.references = references | ||||||
| } | ||||||
| } | ||||||
|
|
||||||
| /// Creates a grouped section with a given name, for example "topics" or "see also" that describes and organizes groups of related API. | ||||||
| /// | ||||||
| /// If each language representation of the API has their own language-specific parameters, pass each language representation's parameter information. | ||||||
| /// | ||||||
| /// If the API has the _same_ parameters in all language representations, only pass the parameters for one language. | ||||||
| /// This produces a "parameters" section that doesn't hide any parameters for any of the languages (same as if the symbol only had one language representation) | ||||||
|
Member
There was a problem hiding this comment.
Suggested change
|
||||||
| func groupedSection(named sectionName: String, groups taskGroups: [SourceLanguage: [TaskGroupInfo]]) -> [XMLNode] { | ||||||
|
Contributor
There was a problem hiding this comment. The comments above are talking about a parameters section. Should we update the comments to describe the task group section this function returns? |
||||||
| let taskGroups = RenderHelpers.sortedLanguageSpecificValues(taskGroups) | ||||||
|
|
||||||
| let items: [XMLElement] = if taskGroups.count == 1 { | ||||||
| taskGroups.first!.value.flatMap { taskGroup in | ||||||
| _singleTaskGroupElements(for: taskGroup) | ||||||
| } | ||||||
| } else { | ||||||
| // TODO: As a future improvement we could diff the references and only mark them as language-specific if the group and reference doesn't appear in all languages. | ||||||
| taskGroups.flatMap { language, taskGroups in | ||||||
| let attribute = XMLNode.attribute(withName: "class", stringValue: "\(language.id)-only") as! XMLNode | ||||||
|
|
||||||
| let elements = taskGroups.flatMap { _singleTaskGroupElements(for: $0) } | ||||||
| for element in elements { | ||||||
| element.addAttribute(attribute) | ||||||
| } | ||||||
| return elements | ||||||
| } | ||||||
| } | ||||||
|
|
||||||
| return selfReferencingSection(named: sectionName, content: items) | ||||||
| } | ||||||
|
|
||||||
| private func _singleTaskGroupElements(for taskGroup: TaskGroupInfo) -> [XMLElement] { | ||||||
| let listItems = taskGroup.references.compactMap { reference in | ||||||
| linkProvider.element(for: reference).map { _taskGroupItem(for: $0) } | ||||||
| } | ||||||
| // Don't return a title or abstract/discussion if this group has no links to display. | ||||||
| guard !listItems.isEmpty else { return [] } | ||||||
|
|
||||||
| var items: [XMLElement] = [] | ||||||
| // Title | ||||||
| if let title = taskGroup.title { | ||||||
| items.append(selfReferencingHeading(level: 3, content: [.text(title)], plainTextTitle: title)) | ||||||
| } | ||||||
| // Abstract/Discussion | ||||||
| for markup in taskGroup.content { | ||||||
| let rendered = visit(markup) | ||||||
| if let element = rendered as? XMLElement { | ||||||
| items.append(element) | ||||||
| } else { | ||||||
| // Wrap any inline content in an element. This is not expected to happen in practice | ||||||
| items.append(.element(named: "p", children: [rendered])) | ||||||
| } | ||||||
| } | ||||||
| // Links | ||||||
| items.append(.element(named: "ul", children: listItems)) | ||||||
|
|
||||||
| return items | ||||||
| } | ||||||
|
|
||||||
| private func _taskGroupItem(for element: LinkedElement) -> XMLElement { | ||||||
| var items: [XMLNode] | ||||||
| switch element.subheadings { | ||||||
| case .single(.conceptual(let title)): | ||||||
|
Contributor
There was a problem hiding this comment. Nice more nested pattern matching :) |
||||||
| items = [.element(named: "p", children: [.text(title)])] | ||||||
|
|
||||||
| case .single(.symbol(let fragments)): | ||||||
| items = switch goal { | ||||||
| case .conciseness: | ||||||
| [ .element(named: "code", children: [.text(fragments.map(\.text).joined())]) ] | ||||||
| case .richness: | ||||||
| [ _symbolSubheading(fragments, languageFilter: nil) ] | ||||||
| } | ||||||
|
|
||||||
| case .languageSpecificSymbol(let fragmentsByLanguage): | ||||||
| let fragmentsByLanguage = RenderHelpers.sortedLanguageSpecificValues(fragmentsByLanguage) | ||||||
| items = if fragmentsByLanguage.count == 1 { | ||||||
| [ _symbolSubheading(fragmentsByLanguage.first!.value, languageFilter: nil) ] | ||||||
| } else if goal == .conciseness, let fragments = fragmentsByLanguage.first?.value { | ||||||
|
Contributor
There was a problem hiding this comment. Are we ignoring the second (and subsequent languages) here for concise mode? Please explain why with a comment. |
||||||
| [ _symbolSubheading(fragments, languageFilter: nil) ] | ||||||
| } else { | ||||||
| fragmentsByLanguage.map { language, fragments in | ||||||
| _symbolSubheading(fragments, languageFilter: language) | ||||||
| } | ||||||
| } | ||||||
| } | ||||||
|
|
||||||
| // Add the formatted abstract if the linked element has one. | ||||||
| if let abstract = element.abstract { | ||||||
| items.append(visit(abstract)) | ||||||
| } | ||||||
|
|
||||||
| return .element(named: "li", children: [ | ||||||
| // Wrap both the name and the abstract in an anchor so that the entire item is a link to that page. | ||||||
| .element(named: "a", children: items, attributes: ["href": path(to: element.path)]) | ||||||
| ]) | ||||||
| } | ||||||
|
|
||||||
| private func _symbolSubheading(_ fragments: [LinkedElement.SymbolNameFragment], languageFilter: SourceLanguage?) -> XMLElement { | ||||||
|
Contributor
There was a problem hiding this comment. An HTML example here or above might be nice; this is getting a bit complex. |
||||||
| switch goal { | ||||||
| case .richness: | ||||||
| .element( | ||||||
| named: "code", | ||||||
| children: fragments.map { | ||||||
| .element(named: "span", children: wordBreak(symbolName: $0.text), attributes: ["class": $0.kind.rawValue]) | ||||||
| }, | ||||||
| attributes: languageFilter.map { ["class": "\($0.id)-only"] } | ||||||
| ) | ||||||
| case .conciseness: | ||||||
| .element( | ||||||
| named: "code", | ||||||
| children: [.text(fragments.map(\.text).joined())], | ||||||
| attributes: languageFilter.map { ["class": "\($0.id)-only"] } | ||||||
| ) | ||||||
| } | ||||||
| } | ||||||
| } | ||||||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
And:
has their->has its