Skip to content

Include more content in the HTML output #1390

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
d-ronnqvist merged 3 commits into from
Dec 12, 2025
Merged

Include more content in the HTML output #1390

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
9a824f5
Include more page content in the HTML output
d-ronnqvist Dec 11, 2025
70011ee
Also add deprecation summaries to the HTML output
d-ronnqvist Dec 11, 2025
c2922dc
Merge branch 'main' into output-html-integrate-2
d-ronnqvist Dec 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
208 changes: 191 additions & 17 deletions Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -157,25 +157,30 @@ struct HTMLRenderer {
mutating func renderArticle(_ article: Article) -> RenderedPageInfo {
let node = context.documentationCache[reference]!

let main = XMLElement(name: "main")
let articleElement = XMLElement(name: "article")
main.addChild(articleElement)

let hero = XMLElement(name: "section")
articleElement.addChild(hero)

// Breadcrumbs and Eyebrow
hero.addChild(renderer.breadcrumbs(
references: (context.shortestFinitePath(to: reference) ?? [context.soleRootModuleReference!]).map { $0.url },
currentPageNames: .single(.conceptual(node.name.plainText))
))
addEyebrow(text: article.topics == nil ? "Article": "API Collection", to: hero)

// Title
hero.addChild(
.element(named: "h1", children: [.text(node.name.plainText)])
)

// Abstract
if let abstract = article.abstract {
let paragraph = renderer.visit(abstract) as! XMLElement
if goal == .richness {
paragraph.addAttribute(XMLNode.attribute(withName: "id", stringValue: "abstract") as! XMLNode)
}
hero.addChild(paragraph)
addAbstract(abstract, to: hero)
}

// Deprecation message
if let deprecationMessage = article.deprecationSummary?.elements {
addDeprecationSummary(markup: deprecationMessage, to: hero)
}

// Discussion
Expand All @@ -185,8 +190,31 @@ struct HTMLRenderer {
)
}

// Topics
if let topics = article.topics {
separateSectionsIfNeeded(in: articleElement)

// TODO: Support language specific topic sections, indicated using @SupportedLanguage directives (rdar://166308418)
articleElement.addChildren(
renderer.groupedSection(named: "Topics", groups: [
.swift: topics.taskGroups.map { group in
.init(title: group.heading?.title, content: group.content, references: group.links.compactMap {
$0.destination.flatMap { URL(string: $0) }
})
}
])
)
}
// Articles don't have _automatic_ topic sections.

// See Also
if let seeAlso = article.seeAlso {
addSeeAlso(seeAlso, to: articleElement)
}
// _Automatic_ See Also sections are very heavily tied into the RenderJSON model and require information from the JSON to determine.

return RenderedPageInfo(
content: goal == .richness ? main : articleElement,
content: articleElement,
metadata: .init(
title: article.title?.plainText ?? node.name.plainText,
plainDescription: article.abstract?.plainText
Expand All @@ -195,13 +223,19 @@ struct HTMLRenderer {
}

mutating func renderSymbol(_ symbol: Symbol) -> RenderedPageInfo {
let main = XMLElement(name: "main")
let articleElement = XMLElement(name: "article")
main.addChild(articleElement)
let node = context.documentationCache[reference]!

let articleElement = XMLElement(name: "article")
let hero = XMLElement(name: "section")
articleElement.addChild(hero)

// Breadcrumbs and Eyebrow
hero.addChild(renderer.breadcrumbs(
references: (context.linkResolver.localResolver.breadcrumbs(of: reference, in: reference.sourceLanguage) ?? []).map { $0.url },
currentPageNames: node.makeNames(goal: goal)
))
addEyebrow(text: symbol.roleHeading, to: hero)

// Title
switch symbol.titleVariants.values(goal: goal) {
case .single(let title):
Expand All @@ -223,11 +257,72 @@ struct HTMLRenderer {

// Abstract
if let abstract = symbol.abstract {
let paragraph = renderer.visit(abstract) as! XMLElement
if goal == .richness {
paragraph.addAttribute(XMLNode.attribute(withName: "id", stringValue: "abstract") as! XMLNode)
addAbstract(abstract, to: hero)
}

// Availability
if let availability = symbol.availability?.availability.filter({ $0.domain != nil }).sorted(by: \.domain!.rawValue),
!availability.isEmpty
{
hero.addChild(
renderer.availability(availability.map { item in
.init(
name: item.domain!.rawValue, // Verified non-empty above
introduced: item.introducedVersion.map { "\($0.major).\($0.minor)" },
deprecated: item.deprecatedVersion.map { "\($0.major).\($0.minor)" },
isBeta: false // TODO: Derive and pass beta information
)
})
)
}

// Declaration
if !symbol.declarationVariants.allValues.isEmpty {
// TODO: Display platform specific declarations

var fragmentsByLanguage = [SourceLanguage: [SymbolGraph.Symbol.DeclarationFragments.Fragment]]()
for (trait, variant) in symbol.declarationVariants.allValues {
guard let language = trait.sourceLanguage else { continue }
fragmentsByLanguage[language] = variant.values.first?.declarationFragments
}
hero.addChild(paragraph)

if fragmentsByLanguage.values.contains(where: { !$0.isEmpty }) {
hero.addChild( renderer.declaration(fragmentsByLanguage) )
}
}

// Deprecation message
if let deprecationMessage = symbol.deprecatedSummary?.content {
addDeprecationSummary(markup: deprecationMessage, to: hero)
}

// Parameters
if let parameterSections = symbol.parametersSectionVariants
.values(goal: goal, by: { $0.parameters.elementsEqual($1.parameters, by: { $0.name == $1.name }) })
.valuesByLanguage()
{
articleElement.addChildren(renderer.parameters(
parameterSections.mapValues { section in
section.parameters.map {
MarkdownRenderer<ContextLinkProvider>.ParameterInfo(name: $0.name, content: $0.contents)
}
}
))
}

// Return value
if !symbol.returnsSectionVariants.allValues.isEmpty {
articleElement.addChildren(
renderer.returns(
.init(
symbol.returnsSectionVariants.allValues.map { trait, returnSection in (
key: trait.sourceLanguage ?? .swift,
value: returnSection.content
)},
uniquingKeysWith: { _, new in new }
)
)
)
}

// Mentioned In
Expand All @@ -246,6 +341,31 @@ struct HTMLRenderer {
)
}

// Topics
do {
// TODO: Support language specific topic sections, indicated using @SupportedLanguage directives (rdar://166308418)
var taskGroupInfo: [MarkdownRenderer<ContextLinkProvider>.TaskGroupInfo] = []

if let authored = symbol.topics?.taskGroups {
taskGroupInfo.append(contentsOf: authored.map { group in
.init(title: group.heading?.title, content: group.content, references: group.links.compactMap {
$0.destination.flatMap { URL(string: $0) }
})
})
}
if let automatic = try? AutomaticCuration.topics(for: node, withTraits: [.swift, .objectiveC], context: context) {
taskGroupInfo.append(contentsOf: automatic.map { group in
.init(title: group.title, content: [], references: group.references.compactMap { $0.url })
})
}

if !taskGroupInfo.isEmpty {
separateSectionsIfNeeded(in: articleElement)

articleElement.addChildren(renderer.groupedSection(named: "Topics", groups: [.swift: taskGroupInfo]))
}
}

// Relationships
if let relationships = symbol.relationshipsVariants
.values(goal: goal, by: { $0.groups.elementsEqual($1.groups, by: { $0 == $1 }) })
Expand All @@ -265,14 +385,68 @@ struct HTMLRenderer {
)
}

// See Also
if let seeAlso = symbol.seeAlso {
addSeeAlso(seeAlso, to: articleElement)
}

return RenderedPageInfo(
content: goal == .richness ? main : articleElement,
content: articleElement,
metadata: .init(
title: symbol.title,
plainDescription: symbol.abstract?.plainText
)
)
}

private func addEyebrow(text: String, to element: XMLElement) {
element.addChild(
.element(named: "p", children: [.text(text)], attributes: goal == .richness ? ["id": "eyebrow"] : [:])
)
}

private func addAbstract(_ abstract: Paragraph, to element: XMLElement) {
let paragraph = renderer.visit(abstract) as! XMLElement
if goal == .richness {
paragraph.addAttribute(XMLNode.attribute(withName: "id", stringValue: "abstract") as! XMLNode)
}
element.addChild(paragraph)
}

private func addDeprecationSummary(markup: [any Markup], to element: XMLElement) {
var children: [XMLNode] = [
.element(named: "p", children: [.text("Deprecated")], attributes: ["class": "label"])
]
for child in markup {
children.append(renderer.visit(child))
}

element.addChild(
.element(named: "blockquote", children: children, attributes: ["class": "aside deprecated"])
)
}

private func separateSectionsIfNeeded(in element: XMLElement) {
guard goal == .richness, ((element.children ?? []).last as? XMLElement)?.name == "section" else {
return
}

element.addChild(.element(named: "hr")) // Separate the sections with a thematic break
}

private func addSeeAlso(_ seeAlso: SeeAlsoSection, to element: XMLElement) {
separateSectionsIfNeeded(in: element)

element.addChildren(
renderer.groupedSection(named: "See Also", groups: [
.swift: seeAlso.taskGroups.map { group in
.init(title: group.heading?.title, content: group.content, references: group.links.compactMap {
$0.destination.flatMap { URL(string: $0) }
})
}
])
)
}

// TODO: As a future enhancement, add another layer on top of this that creates complete HTML pages (both `<head>` and `<body>`) (rdar://165912669)
}
Expand Down
Loading