Populate symbol kind in external render nodes

[anferbui]

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:

1. Propagating the OutOfProcessReferenceResolver.ResolvedInformation's documentation kind to LinkResolver.ExternalEntity, the type which is used to deal with external entities.
2. Convert the documentation kind into a symbol kind, following an already existing mapping but in reverse.
3. 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:

1. Use example bundle: Example.docc.zip
   • The bundle contains a link resolver executable for resolving external entities
2. Run DOCC_LINK_RESOLVER_EXECUTABLE=Example.docc/bin/test-data-external-resolver swift run docc preview Example.docc
3. Verify that the navigator page icons in http://localhost:8080/documentation/article look as expected
4. 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]

@swift-ci please test

[sofiaromorales]

I'm unsure about the usage of renderIdentifier.

[sofiaromorales]

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

[anferbui]

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.

[sofiaromorales]

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.

[anferbui]

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)