Populate symbol kind in external render nodes #1251

anferbui · 2025-07-21T13:44:19Z

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

Summary

Fixes the navigator page type for external render nodes such that it takes into account the kind of symbol of the node.

In order to properly determine the navigator page type for a symbol, we need to know its symbol kind:

swift-docc/Sources/SwiftDocC/Indexing/Navigator/RenderNode+NavigatorIndex.swift

Lines 148 to 168 in 65aaf92

    
               /// Returns the type of page for the render node. 
        
               func navigatorPageType() -> NavigatorIndex.PageType { 
        
                   // This is a workaround to support plist keys. 
        
                   switch metadata.roleHeading?.lowercased() { 
        
                       case "property list key":           return .propertyListKey 
        
                       case "property list key reference": return .propertyListKeyReference 
        
                       default: break 
        
                   } 
        
                   switch kind { 
        
                       case .article:  return metadata.role.map { .init(role: $0) } 
        
                                           ?? .article 
        
                       case .tutorial: return .tutorial 
        
                       case .section:  return .section 
        
                       case .overview: return .overview 
        
                       case .symbol:   return metadata.symbolKind.map { .init(symbolKind: $0) } 
        
                                           ?? metadata.role.map { .init(role: $0) } 
        
                                           ?? .symbol 
        
                   } 
        
               } 
        
           }

However, the symbol kind was not available for external nodes and all items were showing as their generic role, e.g. "article" or "symbol".

This PR adds logic to derive an external render node's symbol kind:

Propagating the OutOfProcessReferenceResolver.ResolvedInformation's documentation kind to LinkResolver.ExternalEntity, the type which is used to deal with external entities.
Convert the documentation kind into a symbol kind, following an already existing mapping but in reverse.
Use the symbol kind's rendering identifier to determine the navigator page type, same as for local render nodes.

Navigator comparison (using swift-docc-render):

Before	After

The navigator icons on the right match the symbol kinds of the external pages.

The navigator index.json shows the correct page type as well:

          {
            "external": true,
            "path": "/resolved/class",
            "title": "Resolved class",
            "type": "class"
          }

Dependencies

N/A.

Testing

Previewed a custom bundle locally which contained different types of external links (module, class, function and article).

Verified that they showed the relevant icon in the navigator when using swift-docc-render.
Verified that the resulting index.json looked as expected

Steps:

Use example bundle: Example.docc.zip
- The bundle contains a link resolver executable for resolving external entities
Run DOCC_LINK_RESOLVER_EXECUTABLE=Example.docc/bin/test-data-external-resolver swift run docc preview Example.docc
Verify that the navigator page icons in http://localhost:8080/documentation/article look as expected
Verify that the navigator JSON at Example.docc/.docc-build/index/index.json looks as expected.

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

anferbui · 2025-07-21T14:10:29Z

@swift-ci please test

sofiaromorales

I'm unsure about the usage of renderIdentifier.

sofiaromorales · 2025-07-28T14:43:31Z

Sources/SwiftDocC/Infrastructure/Link Resolution/LinkResolver.swift

+        ///   - documentationKind: The kind of external content that's being referenced.
        @_spi(ExternalLinks)
-        public init(topicRenderReference: TopicRenderReference, renderReferenceDependencies: RenderReferenceDependencies, sourceLanguages: Set<SourceLanguage>) {
+        public init(topicRenderReference: TopicRenderReference, renderReferenceDependencies: RenderReferenceDependencies, sourceLanguages: Set<SourceLanguage>, documentationKind: DocumentationNode.Kind) {


This is a public API, shouldn't we deprecate it and create a new initializer?

I didn't do this because it's experimental API and comes with a warning:

swift-docc/Sources/SwiftDocC/Infrastructure/Link Resolution/LinkResolver.swift

Lines 44 to 45 in 65aaf92

@_spi(ExternalLinks) // This isn't stable API yet.

public struct ExternalEntity {

WDYT? Happy to do as you suggested.

I've updated this init and now the new parameter is optional

sofiaromorales · 2025-07-28T14:51:22Z

Sources/SwiftDocC/Infrastructure/Link Resolution/LinkResolver+NavigatorIndex.swift

            externalID: renderNode.externalIdentifier.identifier,
            role: renderNode.role,
-            symbolKind: renderNode.symbolKind?.identifier,
+            symbolKind: renderNode.symbolKind?.renderingIdentifier,


From

swift-docc/Sources/SwiftDocC/Semantics/Graph/SymbolKind.Swift.swift

Line 27 in 1b4a185

var renderingIdentifier: String {

it seems like ideally we don't want to use the renderingIdentifier.

renderingIdentifier is what we use for deriving the navigator symbol kind for local items -- for consistency I think we should use the same.

swift-docc/Sources/SwiftDocC/Model/Rendering/RenderNodeTranslator.swift

Lines 1299 to 1301 in 65aaf92

node.metadata.symbolKindVariants = VariantCollection<String?>(from: symbol.kindVariants) { _, kindVariants in

kindVariants.identifier.renderingIdentifier

} ?? .init(defaultValue: nil)

d-ronnqvist · 2025-08-14T16:01:23Z

Sources/SwiftDocC/Infrastructure/Link Resolution/LinkResolver.swift

+        /// The kind of external content that's being referenced.
+        ///
+        /// For example, the navigator requires specific knowledge about what type of external symbol is being linked to.
+        var documentationKind: DocumentationNode.Kind


Is it necessary to store a DocumentationNode.Kind if we only need to access the symbol identifier that's derived from it?

Not necessary to store the whole documentation kind, as we need only the symbol kind. Updated to only store the symbol kind in e7bada9

d-ronnqvist · 2025-08-14T16:04:51Z

Sources/SwiftDocC/Infrastructure/Link Resolution/LinkResolver+NavigatorIndex.swift

    var symbolKind: SymbolGraph.Symbol.KindIdentifier? {
-        // Symbol kind information is not available for external entities
-        return nil
+        DocumentationNode.symbolKind(for: externalEntity.documentationKind)


Is this value different from externalEntity.topicRenderReference.role.map { init(rawValue: $0) }?

Yes, externalEntity.topicRenderReference.role is derived using this function, which for symbols only returns .symbol, and not which type of symbol it is.

The symbol kinds we're looking for here are more specific i.e. class, func.

There is a mapping from `SymbolGraph.Symbol.KindIdentifier` to `DocumentationNode.Kind`, but not the other way around; this commit adds one. For documentation kinds which both map to the same symbol kind, this has been expressed as: - both documentation kinds are converted to the same symbol kind in `symbolKind(for:)`. - a specific documentation kind is chosen as the default mapping in `kind(forKind:)` For example, for `DocumentationNode.Kind. typeConstant` [1]: - both `symbolKind(for: .typeConstant)` and `symbolKind(for: .typeProperty)` return `.typeProperty` - `kind(forKind: .typeProperty)` returns `.typeProperty` This function will be used to map and external entity's documentation kind to a symbol kind, so that that information can be populated as part of the navigator. ## Verification: This has been verified by testing the round trip conversion of all symbol kinds, and all documentation kinds which are symbols. [1]: https://github.com/swiftlang/swift-docc/blob/65aaf926ec079ddbd40f29540d4180a70af99e5e/Sources/SwiftDocC/Model/Kind.swift#L151

Adds a new property to `LinkResolver.ExternalEntity` which stores the symbol kind of the external entity. This is derived at the level of `OutOfProcessReferenceResolver.ResolvedInformation`, which has access to the documentation kind [1] and already uses it to derive the render node kind and role, but then discards it. This commit adds logic to `OutOfProcessReferenceResolver.ResolvedInformation` to derive the symbol kind from the documentation kind, then capture that in `LinkResolver.ExternalEntity. We need access to the documentation kind in order to resolve the symbol kind as part of computing the navigator title. [2] [1]: https://github.com/swiftlang/swift-docc/blob/65aaf926ec079ddbd40f29540d4180a70af99e5e/Sources/SwiftDocC/Infrastructure/External%20Data/OutOfProcessReferenceResolver.swift#L564-L565 [2]: https://github.com/swiftlang/swift-docc/blob/65aaf926ec079ddbd40f29540d4180a70af99e5e/Sources/SwiftDocC/Indexing/Navigator/RenderNode%2BNavigatorIndex.swift#L163

Propagates the symbol kind value from `LinkResolver.ExternalEntity` to the `ExternalRenderNode` used for generating the navigation index for external render nodes. This completes adding symbol kind support for external entities in the navigator. Also updates how the symbol kind is propagated to the navigator metadata, by using `.renderingIdentifier` over `.identifier`, to match the behaviour of local nodes [1]. Fixes rdar://156487928. [1]: https://github.com/swiftlang/swift-docc/blob/65aaf926ec079ddbd40f29540d4180a70af99e5e/Sources/SwiftDocC/Model/Rendering/RenderNodeTranslator.swift#L1300

anferbui · 2025-09-15T13:27:25Z

@swift-ci please test

sofiaromorales

🔥

anferbui requested a review from sofiaromorales July 21, 2025 13:44

anferbui mentioned this pull request Jul 24, 2025

Populate abbreviated declaration fragments in external render nodes #1255

Merged

3 tasks

sofiaromorales reviewed Jul 28, 2025

View reviewed changes

d-ronnqvist reviewed Aug 14, 2025

View reviewed changes

anferbui added 3 commits September 15, 2025 14:00

anferbui force-pushed the symbol-kind-in-external-render-nodes branch from 8173968 to ca3986e Compare September 15, 2025 13:25

sofiaromorales approved these changes Sep 15, 2025

View reviewed changes

anferbui merged commit 3268e73 into swiftlang:main Sep 15, 2025
2 checks passed

anferbui deleted the symbol-kind-in-external-render-nodes branch September 15, 2025 14:52

	/// Returns the type of page for the render node.
	func navigatorPageType() -> NavigatorIndex.PageType {
	// This is a workaround to support plist keys.
	switch metadata.roleHeading?.lowercased() {
	case "property list key": return .propertyListKey
	case "property list key reference": return .propertyListKeyReference
	default: break
	}

	switch kind {
	case .article: return metadata.role.map { .init(role: $0) }
	?? .article
	case .tutorial: return .tutorial
	case .section: return .section
	case .overview: return .overview
	case .symbol: return metadata.symbolKind.map { .init(symbolKind: $0) }
	?? metadata.role.map { .init(role: $0) }
	?? .symbol
	}
	}
	}

	@_spi(ExternalLinks) // This isn't stable API yet.
	public struct ExternalEntity {

	node.metadata.symbolKindVariants = VariantCollection<String?>(from: symbol.kindVariants) { _, kindVariants in
	kindVariants.identifier.renderingIdentifier
	} ?? .init(defaultValue: nil)

Populate symbol kind in external render nodes #1251

Populate symbol kind in external render nodes #1251

Uh oh!

Conversation

anferbui commented Jul 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Navigator comparison (using swift-docc-render):

Dependencies

Testing

Checklist

Uh oh!

anferbui commented Jul 21, 2025

Uh oh!

sofiaromorales left a comment

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!

Choose a reason for hiding this comment

Uh oh!

anferbui commented Sep 15, 2025

Uh oh!

sofiaromorales left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

anferbui commented Jul 21, 2025 •

edited

Loading