Skip to content

Commit 8fe0e0b

Browse files
d-ronnqvistd-ronnqvist
committed
Further minimize the concise HTML by avoiding most <section> elements
1 parent 7225dd9 commit 8fe0e0b

File tree

7 files changed

+205
-189
lines changed

7 files changed

+205
-189
lines changed

‎Sources/DocCHTML/MarkupRenderer+Parameters.swift‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ package extension MarkdownRenderer {
2828
}
2929
}
3030

31-
func parameters(_ info: [SourceLanguage: [ParameterInfo]]) -> XMLElement {
31+
func parameters(_ info: [SourceLanguage: [ParameterInfo]]) -> [XMLNode] {
3232
let info = RenderHelpers.sortedLanguageSpecificValues(info)
3333
let items: [XMLElement] = switch info.count {
3434
case 1:

‎Sources/DocCHTML/MarkupRenderer+Returns.swift‎

Lines changed: 13 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ package import Markdown
1818
package import DocCCommon
1919

2020
package extension MarkdownRenderer {
21-
func returns(_ languageSpecificSections: [SourceLanguage: [any Markup]]) -> XMLElement {
21+
func returns(_ languageSpecificSections: [SourceLanguage: [any Markup]]) -> [XMLNode] {
2222
let info = RenderHelpers.sortedLanguageSpecificValues(languageSpecificSections)
2323
let items: [XMLNode] = if info.count == 1 {
2424
info.first!.value.map { visit($0) } // Verified to exist above
@@ -43,25 +43,23 @@ package extension MarkdownRenderer {
4343
return selfReferencingSection(named: "Return Value", content: items)
4444
}
4545

46-
func selfReferencingSection(named sectionName: String, content: [XMLNode]) -> XMLElement {
47-
let headingContent: XMLNode
48-
let sectionAttributes: [String: String]
49-
46+
func selfReferencingSection(named sectionName: String, content: [XMLNode]) -> [XMLNode] {
5047
switch goal {
5148
case .richness:
5249
let id = urlReadableFragment(sectionName.lowercased())
53-
headingContent = .element(named: "a", children: [.text(sectionName)], attributes: ["href": "#\(id)"])
54-
sectionAttributes = ["id": id]
50+
51+
return [.element(
52+
named: "section",
53+
children: [
54+
.element(named: "h2", children: [
55+
.element(named: "a", children: [.text(sectionName)], attributes: ["href": "#\(id)"])
56+
])
57+
] + content,
58+
attributes: ["id": id]
59+
)]
5560
case .conciseness:
56-
headingContent = .text(sectionName)
57-
sectionAttributes = [:]
61+
return [.element(named: "h2", children: [.text(sectionName)]) as XMLNode] + content
5862
}
59-
60-
return .element(
61-
named: "section",
62-
children: [.element(named: "h2", children: [headingContent])] + content,
63-
attributes: sectionAttributes
64-
)
6563
}
6664
}
6765

‎Sources/DocCHTML/MarkupRenderer+Topics.swift‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ package extension MarkdownRenderer {
3030
}
3131
}
3232

33-
func groupedSection(named sectionName: String, groups taskGroups: [SourceLanguage: [TaskGroupInfo]]) -> XMLElement {
33+
func groupedSection(named sectionName: String, groups taskGroups: [SourceLanguage: [TaskGroupInfo]]) -> [XMLNode] {
3434
let taskGroups = RenderHelpers.sortedLanguageSpecificValues(taskGroups)
3535

3636
let items: [XMLElement] = if taskGroups.count == 1 {

‎Sources/SwiftDocC/Model/Rendering/HTML/HTMLRenderer.swift‎

Lines changed: 18 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -218,7 +218,7 @@ struct HTMLRenderer {
218218

219219
// Discussion
220220
if let discussion = article.discussion {
221-
articleElement.addChild(makeDiscussion(discussion, isSymbol: false))
221+
articleElement.addChildren(makeDiscussion(discussion, isSymbol: false))
222222
}
223223

224224
func separateCurationIfNeeded() {
@@ -234,7 +234,7 @@ struct HTMLRenderer {
234234
separateCurationIfNeeded()
235235

236236
// TODO: Support language specific topic sections
237-
articleElement.addChild(
237+
articleElement.addChildren(
238238
renderer.groupedSection(named: "Topics", groups: [
239239
.swift: topics.taskGroups.map { group in
240240
.init(title: group.heading?.title, content: group.content, references: group.links.compactMap {
@@ -250,7 +250,7 @@ struct HTMLRenderer {
250250
if let seeAlso = article.seeAlso {
251251
separateCurationIfNeeded()
252252

253-
articleElement.addChild(
253+
articleElement.addChildren(
254254
renderer.groupedSection(named: "See Also", groups: [
255255
.swift: seeAlso.taskGroups.map { group in
256256
.init(title: group.heading?.title, content: group.content, references: group.links.compactMap {
@@ -405,7 +405,7 @@ struct HTMLRenderer {
405405

406406
// Parameters
407407
if !symbol.parametersSectionVariants.allValues.isEmpty {
408-
articleElement.addChild(
408+
articleElement.addChildren(
409409
renderer.parameters(
410410
.init(
411411
symbol.parametersSectionVariants.allValues.map { trait, parameters in (
@@ -423,7 +423,7 @@ struct HTMLRenderer {
423423

424424
// Return value
425425
if !symbol.returnsSectionVariants.allValues.isEmpty {
426-
articleElement.addChild(
426+
articleElement.addChildren(
427427
renderer.returns(
428428
.init(
429429
symbol.returnsSectionVariants.allValues.map { trait, returnSection in (
@@ -450,7 +450,7 @@ struct HTMLRenderer {
450450

451451
let mentions = context.articleSymbolMentions.articlesMentioning(reference)
452452
if !mentions.isEmpty {
453-
articleElement.addChild(
453+
articleElement.addChildren(
454454
renderer.selfReferencingSection(named: "Mentioned In", content: [
455455
.element(named: "ul", children: mentions.compactMap { reference in
456456
context.documentationCache[reference].map { .element(named: "li", children: [.text($0.name.description)]) }
@@ -464,7 +464,7 @@ struct HTMLRenderer {
464464
if let discussion = symbol.discussion {
465465
separateCurationIfNeeded()
466466

467-
articleElement.addChild(makeDiscussion(discussion, isSymbol: true))
467+
articleElement.addChildren(makeDiscussion(discussion, isSymbol: true))
468468
}
469469

470470
// Topics
@@ -488,15 +488,15 @@ struct HTMLRenderer {
488488
if !taskGroupInfo.isEmpty {
489489
separateCurationIfNeeded()
490490

491-
articleElement.addChild(renderer.groupedSection(named: "Topics", groups: [.swift: taskGroupInfo]))
491+
articleElement.addChildren(renderer.groupedSection(named: "Topics", groups: [.swift: taskGroupInfo]))
492492
}
493493
}
494494

495495
// See Also
496496
if let seeAlso = symbol.seeAlso {
497497
separateCurationIfNeeded()
498498

499-
articleElement.addChild(
499+
articleElement.addChildren(
500500
renderer.groupedSection(named: "See Also", groups: [
501501
.swift: seeAlso.taskGroups.map { group in
502502
.init(title: group.heading?.title, content: group.content, references: group.links.compactMap {
@@ -517,7 +517,7 @@ struct HTMLRenderer {
517517
)
518518
}
519519

520-
private func makeDiscussion(_ discussion: DiscussionSection, isSymbol: Bool) -> XMLNode {
520+
private func makeDiscussion(_ discussion: DiscussionSection, isSymbol: Bool) -> [XMLNode] {
521521
var remaining = discussion.content[...]
522522

523523
let title: String
@@ -541,3 +541,11 @@ private extension DocumentationDataVariantsTrait {
541541
(lhs.interfaceLanguage ?? "") < (rhs.interfaceLanguage ?? "")
542542
}
543543
}
544+
545+
private extension XMLElement {
546+
func addChildren(_ nodes: [XMLNode]) {
547+
for node in nodes {
548+
addChild(node)
549+
}
550+
}
551+
}

‎Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift‎

Lines changed: 84 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -116,22 +116,39 @@ struct MarkdownRenderer_PageElementsTests {
116116
""")),
117117
]
118118
])
119-
let expectedHTMLStart = switch goal {
120-
case .richness: """
119+
120+
switch goal {
121+
case .richness:
122+
#expect(parameters.rendered(prettyFormatted: true) == """
121123
<section id="parameters">
122124
<h2>
123125
<a href="#parameters">Parameters</a>
124126
</h2>
125-
"""
126-
case .conciseness: """
127-
<section>
127+
<dl>
128+
<dt>
129+
<code>First</code>
130+
</dt>
131+
<dd>
132+
<p>Some <i>formatted</i>
133+
description with <code>code</code>
134+
</p>
135+
</dd>
136+
<dt>
137+
<code>Second</code>
138+
</dt>
139+
<dd>
140+
<p>Some <b>other</b>
141+
<i>formatted</i>
142+
description</p>
143+
<p>That spans two paragraphs</p>
144+
</dd>
145+
</dl>
146+
</section>
147+
""")
148+
case .conciseness:
149+
#expect(parameters.rendered(prettyFormatted: true) == """
128150
<h2>Parameters</h2>
129-
"""
130-
}
131-
132-
#expect(parameters.rendered(prettyFormatted: true) == """
133-
\(expectedHTMLStart)
134-
<dl>
151+
<dl>
135152
<dt>
136153
<code>First</code>
137154
</dt>
@@ -149,9 +166,9 @@ struct MarkdownRenderer_PageElementsTests {
149166
description</p>
150167
<p>That spans two paragraphs</p>
151168
</dd>
152-
</dl>
153-
</section>
154-
""")
169+
</dl>
170+
""")
171+
}
155172
}
156173

157174
@Test
@@ -312,25 +329,28 @@ struct MarkdownRenderer_PageElementsTests {
312329
let parameters = makeRenderer(goal: goal).returns([
313330
.swift: parseMarkup(string: "First paragraph\n\nSecond paragraph")
314331
])
315-
let expectedHTMLStart = switch goal {
316-
case .richness: """
332+
333+
let commonHTML = """
334+
<p>First paragraph</p>
335+
<p>Second paragraph</p>
336+
"""
337+
338+
switch goal {
339+
case .richness:
340+
#expect(parameters.rendered(prettyFormatted: true) == """
317341
<section id="return-value">
318342
<h2>
319343
<a href="#return-value">Return Value</a>
320344
</h2>
321-
"""
322-
case .conciseness: """
323-
<section>
345+
\(commonHTML)
346+
</section>
347+
""")
348+
case .conciseness:
349+
#expect(parameters.rendered(prettyFormatted: true) == """
324350
<h2>Return Value</h2>
325-
"""
351+
\(commonHTML)
352+
""")
326353
}
327-
328-
#expect(parameters.rendered(prettyFormatted: true) == """
329-
\(expectedHTMLStart)
330-
<p>First paragraph</p>
331-
<p>Second paragraph</p>
332-
</section>
333-
""")
334354
}
335355

336356
@Test(arguments: RenderGoal.allCases)
@@ -339,26 +359,29 @@ struct MarkdownRenderer_PageElementsTests {
339359
.swift: parseMarkup(string: "First paragraph\n\nSecond paragraph"),
340360
.objectiveC: parseMarkup(string: "Other language's paragraph"),
341361
])
342-
let expectedHTMLStart = switch goal {
343-
case .richness: """
362+
363+
let commonHTML = """
364+
<p class="swift-only">First paragraph</p>
365+
<p class="swift-only">Second paragraph</p>
366+
<p class="occ-only">Other language’s paragraph</p>
367+
"""
368+
369+
switch goal {
370+
case .richness:
371+
#expect(parameters.rendered(prettyFormatted: true) == """
344372
<section id="return-value">
345373
<h2>
346374
<a href="#return-value">Return Value</a>
347375
</h2>
348-
"""
349-
case .conciseness: """
350-
<section>
376+
\(commonHTML)
377+
</section>
378+
""")
379+
case .conciseness:
380+
#expect(parameters.rendered(prettyFormatted: true) == """
351381
<h2>Return Value</h2>
352-
"""
382+
\(commonHTML)
383+
""")
353384
}
354-
355-
#expect(parameters.rendered(prettyFormatted: true) == """
356-
\(expectedHTMLStart)
357-
<p class="swift-only">First paragraph</p>
358-
<p class="swift-only">Second paragraph</p>
359-
<p class="occ-only">Other language’s paragraph</p>
360-
</section>
361-
""")
362385
}
363386

364387
@Test(arguments: RenderGoal.allCases)
@@ -586,33 +609,31 @@ struct MarkdownRenderer_PageElementsTests {
586609
""")
587610
case .conciseness:
588611
#expect(groupedSection.rendered(prettyFormatted: true) == """
589-
<section>
590612
<h2>\(expectedGroupTitle)</h2>
591613
<h3>Group title</h3>
592614
<p>Some description of this group</p>
593615
<ul>
594-
<li>
595-
<a href="../../SomeClass/index.html">
596-
<code>class SomeClass</code>
597-
<p>Some <i>formatted</i>
598-
description of this class</p>
599-
</a>
600-
</li>
601-
<li>
602-
<a href="../../SomeArticle/index.html">
603-
<p>Some Article</p>
604-
<p>Some <b>formatted</b>
605-
description of this <i>article</i>
606-
.</p>
607-
</a>
608-
</li>
609-
<li>
610-
<a href="../../SomeClass/someMethod(with:and:)/index.html">
611-
<code>func someMethod(with: Int, and: String)</code>
612-
</a>
613-
</li>
616+
<li>
617+
<a href="../../SomeClass/index.html">
618+
<code>class SomeClass</code>
619+
<p>Some <i>formatted</i>
620+
description of this class</p>
621+
</a>
622+
</li>
623+
<li>
624+
<a href="../../SomeArticle/index.html">
625+
<p>Some Article</p>
626+
<p>Some <b>formatted</b>
627+
description of this <i>article</i>
628+
.</p>
629+
</a>
630+
</li>
631+
<li>
632+
<a href="../../SomeClass/someMethod(with:and:)/index.html">
633+
<code>func someMethod(with: Int, and: String)</code>
634+
</a>
635+
</li>
614636
</ul>
615-
</section>
616637
""")
617638
}
618639
}

‎Tests/DocCHTMLTests/MarkdownRendererTests.swift‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -619,6 +619,13 @@ extension Sequence<XMLNode> {
619619
}
620620
}
621621

622+
extension Sequence<XMLElement> {
623+
func rendered(prettyFormatted: Bool) -> String {
624+
map { $0.rendered(prettyFormatted: prettyFormatted) }
625+
.joined(separator: prettyFormatted ? "\n" : "")
626+
}
627+
}
628+
622629
struct SingleValueLinkProvider: LinkProvider {
623630
var elementToReturn: LinkedElement?
624631
func element(for path: URL) -> LinkedElement? {

0 commit comments

Comments
 (0)