set reference roles with PageKind directive (#474)

rdar://104980714

Author: QuietMisdreavus

Sources/SwiftDocC/Model/Rendering/DocumentationContentRenderer.swift

@@ -127,14 +127,20 @@ public class DocumentationContentRenderer {
 
     /// Returns a metadata role for an article, depending if it's a collection, technology, or a free form article.
     func roleForArticle(_ article: Article, nodeKind: DocumentationNode.Kind) -> RenderMetadata.Role {
+        // If the article has a `@PageKind` directive, use the kind from there
+        // before checking anything else.
+        if let pageKind = article.metadata?.pageKind {
+            return pageKind.kind.renderRole
+        }
+
         // We create generated nodes with a semantic Article because they
         // can have doc extensions and the only way to tell them apart from
         // api collections or other articles is by their node kind.
         switch nodeKind {
         case .collectionGroup: return role(for: nodeKind)
         default: break
         }
-        
+
         if article.topics?.taskGroups.isEmpty == false {
             // The documentation includes a "Topics" section, it's a collection or a group
             let isTechnologyRoot = article.metadata?.technologyRoot != nil

Tests/SwiftDocCTests/Rendering/PageKindTests.swift

@@ -74,6 +74,27 @@ class PageKindTests: XCTestCase {
         XCTAssertEqual(renderNode.metadata.roleHeading, "Article")
     }
 
+    func testPageKindReference() throws {
+        let (bundle, context) = try testBundleAndContext(named: "SampleBundle")
+        let reference = ResolvedTopicReference(
+            bundleIdentifier: bundle.identifier,
+            path: "/documentation/SomeSample",
+            sourceLanguage: .swift
+        )
+        let article = try XCTUnwrap(context.entity(with: reference).semantic as? Article)
+        var translator = RenderNodeTranslator(
+            context: context,
+            bundle: bundle,
+            identifier: reference,
+            source: nil
+        )
+        let renderNode = try XCTUnwrap(translator.visitArticle(article) as? RenderNode)
+
+        let sampleReference = try XCTUnwrap(renderNode.references["doc://org.swift.docc.sample/documentation/SampleBundle/MyLocalSample"] as? TopicRenderReference)
+
+        XCTAssertEqual(sampleReference.role, RenderMetadata.Role.sampleCode.rawValue)
+    }
+
     func testValidMetadataWithOnlyPageKind() throws {
         let source = """
         @Metadata {