Include manually-curated articles and other non-symbol nodes in Topics sections

Hi everyone!

I've noticed that articles and other types of non-symbols documentation pages are being filtered out from the manually curated topics section of a ObjC symbol.

I'm encountering this issue because I have a framework with both Swift and ObjC symbols. Additionally, as part of the framework's DocC catalog, there is an article that primarily describes Swift-related concepts and uses the @SupportedLanguage directive set to Swift. The problem arises when I attempt to curate that article in the Topics section of a symbol that's available in ObjC; the curation of the article gets dropped in the ObjC variant page.

This behaviour seems incorrect since I would expect articles to appear in all the variants of any symbol.

This happens because DocC has logic that eliminates any target node from the topics section if the source language of the target node is included in the available source languages of the selected symbol but is different from the chosen symbol variant. The current implementation of DocC assigns the language Swift as the default source language to articles and other kinds of non-symbol nodes. As a result, situations arise where these nodes are removed from the Topics section of ObjC symbols. https://github.com/apple/swift-docc/blob/main/Sources/SwiftDocC/Model/Rendering/RenderNodeTranslator.swift#L1036-L1060

The ideal solution would be to set articles and other non-symbol nodes with a language-less value, as conceptually, this makes the most sense for a file that is describing some kind of conceptual content. However, implementing this solution would require significant refactoring, and might potentially introduce more issues than those we aim to address.

Currently, this is an edge case, but it might become more problematic with the work that has been happening for linking capabilities between documentation of multiple targets. As an example, it will not be possible to curate, in the ObjC variant of a symbol, an article from an article-only doc (which only has Swift as the available source language).

In the meantime, to address this problem, I've opened a pull request that, as a workaround, always includes in the topics section any manually curated non-symbol node, regardless of their perceived programming language

I look forward to any comments you might have.

2 Likes

This makes sense to me. Articles are 'conceptual' documentation that in most cases, shouldn't be considered language-specific, and you'd want to be able to curate them in any language variant of other pages.

1 Like