Add a helper function for rendering a Topics/SeeAlso section as HTML #1382

d-ronnqvist · 2025-12-05T13:29:26Z

Bug/issue #, if applicable: rdar://163326857

Summary

This is another slice of #1366

It adds a helper function to the DocCHTML/MarkdownRenderer to render "topics" and "see also" sections as HTML.

Dependencies

None.

Testing

Nothing in particular for this PR. It only adds an internal helper function. See #1366 for how it eventually does get used.

Checklist

Make sure you check off the following items. If they cannot be completed, provide a reason.

Added tests
Ran the ./bin/test script and it succeeded
Updated documentation if necessary

rdar://163326857

d-ronnqvist · 2025-12-05T13:29:34Z

@swift-ci please test

heckj · 2025-12-05T21:13:59Z

Sources/DocCHTML/MarkdownRenderer+Topics.swift

+
+    /// 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.


Suggested change

/// If each language representation of the API has their own language-specific parameters, pass each language representation's parameter information.

/// If each language representation of the API has their own language-specific set of parameters, pass the parameter information for each language representation.

And: has their -> has its

Fixed in 2931e98

heckj · 2025-12-05T21:14:31Z

Sources/DocCHTML/MarkdownRenderer+Topics.swift

+    /// 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)


Suggested change

/// 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)

/// This produces a "parameters" section that doesn't hide any parameters for any of the languages (the same as if the symbol only had one language representation).

Fixed in 2931e98

heckj · 2025-12-05T21:17:48Z

Tests/DocCHTMLTests/MarkdownRenderer+PageElementsTests.swift

+
+        let renderer = makeRenderer(goal: goal, elementsToReturn: elements)
+        let expectedSectionID = expectedGroupTitle.replacingOccurrences(of: " ", with: "-")
+        let groupedSection = renderer.groupedSection(named: expectedGroupTitle, groups: [


Since you've included the OCC representation with alternate parameters above, could we also include (or make a second set of asserts) that show the expected output when the language is ObjC?

What language is specified here doesn't impact the output. This is testing the same task groups in all languages but the names/subheadings of referenced symbols have difference names in each language. You can see in the "rich" test assertion that the the output contains both titles as <code class="swift-only"> and <code class="occ-only"> elements inside the same anchor.

patshaughnessy · 2025-12-06T01:06:45Z

Sources/DocCHTML/MarkdownRenderer+Topics.swift

+    ///
+    /// 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)
+    func groupedSection(named sectionName: String, groups taskGroups: [SourceLanguage: [TaskGroupInfo]]) -> [XMLNode] {


The comments above are talking about a parameters section. Should we update the comments to describe the task group section this function returns?

Good catch. I updated these comments in 2931e98

Sources/DocCHTML/MarkdownRenderer+Topics.swift

patshaughnessy · 2025-12-06T01:12:22Z

Sources/DocCHTML/MarkdownRenderer+Topics.swift

+            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 {


Are we ignoring the second (and subsequent languages) here for concise mode? Please explain why with a comment.

I added a short comment that describes this in 2931e98

patshaughnessy · 2025-12-06T01:13:16Z

Sources/DocCHTML/MarkdownRenderer+Topics.swift

+        ])
+    }
+
+    private func _symbolSubheading(_ fragments: [LinkedElement.SymbolNameFragment], languageFilter: SourceLanguage?) -> XMLElement {


An HTML example here or above might be nice; this is getting a bit complex.

I added two examples of this in 2931e98

d-ronnqvist · 2025-12-09T15:25:57Z

@swift-ci please test

…wiftlang#1382) * Add a helper function for rendering a Topics/SeeAlso section as HTML rdar://163326857 * Add more code comments and internal documentation comments * Very slightly correct the test data

…1402) * Add a new target for rendering Markdown content into static HTML (#1369) * Add a new target for rendering content into static HTML rdar://163326857 * Include documentation comments with examples for the various `visit(_:)` methods. * Document what a `LinkedAsset` represents * Add code comments to explain how the inline HTML markup is parsed * Don't lowercase anchors for self-referencing headings * Avoid nested scopes when switching over names * Add a code comment about what an "autolink" is * Add a helper function for rendering availability information as HTML (#1376) rdar://163326857 * Add a helper function for rendering page breadcrumbs as HTML (#1378) * Add a helper function for rendering page breadcrumbs as HTML rdar://163326857 * Apply wording suggestion in documentation comment Co-authored-by: Joseph Heck <j_heck@apple.com> --------- Co-authored-by: Joseph Heck <j_heck@apple.com> * Add a helper function for rendering a parameters section as HTML (#1377) * Add a helper function for rendering a parameters section as HTML rdar://163326857 * Apply wording suggestions in documentation comments Co-authored-by: Pat Shaughnessy <pat_shaughnessy@apple.com> Co-authored-by: Joseph Heck <j_heck@apple.com> * Add TODO comment about a debug assertion for the parameter name order --------- Co-authored-by: Pat Shaughnessy <pat_shaughnessy@apple.com> Co-authored-by: Joseph Heck <j_heck@apple.com> * Add tests for parsing of inline HTML when rendering markdown as HTML (#1379) * Add test about parsing inline HTML except for comments * Extract inner HTML parsing code into a private function * Fix minor spelling in code comment Co-authored-by: Pat Shaughnessy <pat_shaughnessy@apple.com> --------- Co-authored-by: Pat Shaughnessy <pat_shaughnessy@apple.com> * Add a helper function for rendering a returns sections as HTML (#1381) * Add a helper function for rendering a returns sections as HTML rdar://163326857 * Minor phrasing updates to the parameter section helper's documentation * Add new source file to Windows CMake file list * Correct grammar in documentation comments Co-authored-by: Pat Shaughnessy <pat_shaughnessy@apple.com> --------- Co-authored-by: Pat Shaughnessy <pat_shaughnessy@apple.com> * Add a helper function for rendering symbol declarations as HTML (#1384) * Add a helper function for rendering symbol declarations as HTML rdar://163326857 * Add code comments to describe why the concise declaration: - Only includes the primary language - Joins the declaration fragments into a single string * Add a helper function for rendering a Topics/SeeAlso section as HTML (#1382) * Add a helper function for rendering a Topics/SeeAlso section as HTML rdar://163326857 * Add more code comments and internal documentation comments * Very slightly correct the test data * Minimally integrate per-page HTML content into each "index.html" file (#1383) * Minimally integrate per-page HTML content into each "index.html" file rdar://163326857 * Extract some common code into private helpers * Move a few common checks into the new private helpers * Add a helper function for rendering a discussion section as HTML (#1388) * Add a helper function for rendering a discussion section as HTML rdar://163326857 * Integrate the discussion section in the HTML renderer * Include Mentioned In and Relationships sections in the HTML output (#1391) * Include more content in the HTML output (#1390) * Include more page content in the HTML output * Also add deprecation summaries to the HTML output --------- Co-authored-by: Joseph Heck <j_heck@apple.com> Co-authored-by: Pat Shaughnessy <pat_shaughnessy@apple.com>

Add a helper function for rendering a Topics/SeeAlso section as HTML

5bec535

rdar://163326857

d-ronnqvist mentioned this pull request Dec 5, 2025

Minimally integrate per-page HTML content into each "index.html" file #1383

Merged

3 tasks

heckj reviewed Dec 5, 2025

View reviewed changes

patshaughnessy approved these changes Dec 6, 2025

View reviewed changes

patshaughnessy mentioned this pull request Dec 6, 2025

Add a helper function for rendering symbol declarations as HTML #1384

Merged

3 tasks

d-ronnqvist added 3 commits December 9, 2025 16:24

Merge branch 'main' into output-html-topics

4925096

Add more code comments and internal documentation comments

2931e98

Very slightly correct the test data

ce7a659

d-ronnqvist merged commit 30a5e34 into swiftlang:main Dec 9, 2025
2 checks passed

d-ronnqvist deleted the output-html-topics branch December 9, 2025 15:31

d-ronnqvist mentioned this pull request Dec 11, 2025

Include more content in the HTML output #1390

Merged

3 tasks

d-ronnqvist mentioned this pull request Dec 17, 2025

[6.3] Integrate per-page HTML content into each "index.html" file" #1402

Merged

	/// If each language representation of the API has their own language-specific parameters, pass each language representation's parameter information.
	/// If each language representation of the API has their own language-specific set of parameters, pass the parameter information for each language representation.

	/// 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)
	/// This produces a "parameters" section that doesn't hide any parameters for any of the languages (the same as if the symbol only had one language representation).

Add a helper function for rendering a Topics/SeeAlso section as HTML #1382

Add a helper function for rendering a Topics/SeeAlso section as HTML #1382

Uh oh!

Conversation

d-ronnqvist commented Dec 5, 2025

Summary

Dependencies

Testing

Checklist

Uh oh!

d-ronnqvist commented Dec 5, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

d-ronnqvist commented Dec 9, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants