Support external links in the navigator

[anferbui]

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

Summary

Adds support for external links in the navigator. To test, used an example DocC catalog with one article and one external reference.

The goal was to have external links which are curated as part of the Topics section show as a navigator node in the final index.json file which powers the navigator. External links should appear under the page under which they were curated, and have a property external=true which marks them as external nodes:

swift-docc/Sources/SwiftDocC/Indexing/RenderIndexJSON/RenderIndex.swift

Lines 247 to 249 in c7660bb

	// Currently Swift-DocC doesn't support resolving links to external DocC archives
	// so we default to `false` here.
	self.isExternal = false

Navigator comparison (using swift-docc-render):

Before	After

There are some fields which we have insufficient information in LinkResolver.ExternalEntity to derive:

• role heading
• platforms
• metadata fragments
• symbol kind

For these cases, they have been documented in source.

The missing fields result in navigator titles differing between the navigator where the page is hosted, and the navigator where the reference is externally linked, particularly for symbols.

For a symbol, the original page & Topics section will show a simplified version of the declaration fragments as the page title, whereas here I have opted for simplicity of using only the shorter title rather than the full declaration fragments (which are the only declaration fragments available as part of the external entity, and used in the Topics section) in order to avoid too much verbosity.

In the future we can improve the quality of the title for external links in order to maintain consistency between the Topics section and navigation index.

Note: We could potentially derive symbol kind, platforms and metadata fragments in the future as the information is present in OutofProcessReferenceResolver.ResolvedInformation, but it would require some rework of the types to propagate the information upwards to LinkResolver.ExternalEntity so I think that's best done in separate PRs and reviewed separately.

Dependencies

N/A

Testing

Steps:

1. Use example bundle:
   Example.docc.zip
2. Set up a link resolver, e.g. using /path/to/swift-docc/bin/test-data-external-resolver and modifying the data as desired
3. Run DOCC_LINK_RESOLVER_EXECUTABLE=/path/to/swift-docc/bin/test-data-external-resolver swift run docc preview Example.docc
4. Verify that the external link is showing in the navigation sidebar as expected.
5. Verify that the index.json is showing the external reference as a node, and that the node has a property external=true:

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

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]

Created this package-level protocol so that we don't have to make a breaking API change to public protocol ConvertOutputConsumer.

[anferbui]

@swift-ci please test

[sofiaromorales]

🔥🔥🔥🔥🔥