add @PageKind directive to set a page's role/title heading

rdar://69902322

Author: QuietMisdreavus

Sources/SwiftDocC/Model/Rendering/RenderNodeTranslator.swift

@@ -817,6 +817,11 @@ public struct RenderNodeTranslator: SemanticVisitor {
                 node.metadata.platformsVariants = .init(defaultValue: renderAvailability)
             }
         }
+
+        if let pageKind = article.metadata?.pageKind {
+            node.metadata.role = pageKind.kind.renderRole.rawValue
+            node.metadata.roleHeading = pageKind.kind.titleHeading
+        }
 
         collectedTopicReferences.append(contentsOf: contentCompiler.collectedTopicReferences)
         node.references = createTopicRenderReferences()

Sources/SwiftDocC/Semantics/Metadata/Metadata.swift

@@ -25,6 +25,7 @@ import Markdown
 /// - ``PageImage``
 /// - ``CallToAction``
 /// - ``Availability``
+/// - ``PageKind``
 public final class Metadata: Semantic, AutomaticDirectiveConvertible {
     public let originalMarkup: BlockDirective
 
@@ -52,6 +53,9 @@ public final class Metadata: Semantic, AutomaticDirectiveConvertible {
 
     @ChildDirective(requirements: .zeroOrMore)
     var availability: [Availability]
+
+    @ChildDirective
+    var pageKind: PageKind? = nil
 
     static var keyPaths: [String : AnyKeyPath] = [
         "documentationOptions"  : \Metadata._documentationOptions,
@@ -61,6 +65,7 @@ public final class Metadata: Semantic, AutomaticDirectiveConvertible {
         "customMetadata"        : \Metadata._customMetadata,
         "callToAction"          : \Metadata._callToAction,
         "availability"          : \Metadata._availability,
+        "pageKind"              : \Metadata._pageKind,
     ]
 
     /// Creates a metadata object with a given markup, documentation extension, and technology root.
@@ -83,7 +88,7 @@ public final class Metadata: Semantic, AutomaticDirectiveConvertible {
 
     func validate(source: URL?, for bundle: DocumentationBundle, in context: DocumentationContext, problems: inout [Problem]) -> Bool {
         // Check that something is configured in the metadata block
-        if documentationOptions == nil && technologyRoot == nil && displayName == nil && pageImages.isEmpty && customMetadata.isEmpty && callToAction == nil && availability.isEmpty {
+        if documentationOptions == nil && technologyRoot == nil && displayName == nil && pageImages.isEmpty && customMetadata.isEmpty && callToAction == nil && availability.isEmpty && pageKind == nil {
             let diagnostic = Diagnostic(
                 source: source,
                 severity: .information,

Sources/SwiftDocC/Semantics/Metadata/PageKind.swift

@@ -0,0 +1,72 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2023 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See https://swift.org/LICENSE.txt for license information
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+import Foundation
+import Markdown
+
+extension Metadata {
+    /// A directive that allows you to set a page's kind, which affects its default title heading and page icon.
+    ///
+    /// The `@PageKind` directive tells Swift-DocC to treat a documentation page as a particular
+    /// "kind". This is used to determine the page's default navigator icon, as well as the default
+    /// title heading on the page itself.
+    ///
+    /// The available page kinds are `article` and `sampleCode`.
+    ///
+    /// This directive is only valid within a `@Metadata` directive:
+    ///
+    /// ```markdown
+    /// @Metadata {
+    ///     @PageKind(sampleCode)
+    /// }
+    /// ```
+    public final class PageKind: Semantic, AutomaticDirectiveConvertible {
+        /// The available kinds for use with the `@PageKind` directive.
+        public enum Kind: String, CaseIterable, DirectiveArgumentValueConvertible {
+            /// An article of free-form text; the default for standalone markdown files.
+            case article
+            /// A page describing a "sample code" project.
+            case sampleCode
+
+            var renderRole: RenderMetadata.Role {
+                switch self {
+                case .article:
+                    return RenderMetadata.Role.article
+                case .sampleCode:
+                    return RenderMetadata.Role.sampleCode
+                }
+            }
+
+            var titleHeading: String {
+                switch self {
+                case .article:
+                    return "Article"
+                case .sampleCode:
+                    return "Sample Code"
+                }
+            }
+        }
+
+        /// The page kind to apply to the page.
+        @DirectiveArgumentWrapped(name: .unnamed)
+        public var kind: Kind
+
+        static var keyPaths: [String : AnyKeyPath] = [
+            "kind" : \PageKind._kind
+        ]
+
+        public let originalMarkup: Markdown.BlockDirective
+
+        @available(*, deprecated, message: "Do not call directly. Required for 'AutomaticDirectiveConvertible'.")
+        init(originalMarkup: Markdown.BlockDirective) {
+            self.originalMarkup = originalMarkup
+        }
+    }
+}

Tests/SwiftDocCTests/Rendering/PageKindTests.swift

@@ -0,0 +1,100 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2023 Apple Inc. and the Swift project authors
+ Licensed under Apache License v2.0 with Runtime Library Exception
+
+ See https://swift.org/LICENSE.txt for license information
+ See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+*/
+
+import Foundation
+import Markdown
+import XCTest
+@testable import SwiftDocC
+
+class PageKindTests: XCTestCase {
+    func testPageKindSampleCode() throws {
+        let (bundle, context) = try testBundleAndContext(named: "SampleBundle")
+        let reference = ResolvedTopicReference(
+            bundleIdentifier: bundle.identifier,
+            path: "/documentation/SampleBundle/MyLocalSample",
+            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)
+
+        XCTAssertEqual(renderNode.metadata.role, RenderMetadata.Role.sampleCode.rawValue)
+        XCTAssertEqual(renderNode.metadata.roleHeading, Metadata.PageKind.Kind.sampleCode.titleHeading)
+    }
+
+    func testPageKindArticle() throws {
+        let (bundle, context) = try testBundleAndContext(named: "SampleBundle")
+        let reference = ResolvedTopicReference(
+            bundleIdentifier: bundle.identifier,
+            path: "/documentation/SampleBundle/MySample",
+            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)
+
+        XCTAssertEqual(renderNode.metadata.role, RenderMetadata.Role.article.rawValue)
+        XCTAssertEqual(renderNode.metadata.roleHeading, Metadata.PageKind.Kind.article.titleHeading)
+    }
+
+    func testPageKindDefault() throws {
+        let (bundle, context) = try testBundleAndContext(named: "AvailabilityBundle")
+        let reference = ResolvedTopicReference(
+            bundleIdentifier: bundle.identifier,
+            path: "/documentation/AvailabilityBundle/ComplexAvailable",
+            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)
+
+        XCTAssertEqual(renderNode.metadata.role, "article")
+        XCTAssertEqual(renderNode.metadata.roleHeading, "Article")
+    }
+
+    func testValidMetadataWithOnlyPageKind() throws {
+        let source = """
+        @Metadata {
+            @PageKind(article)
+        }
+        """
+
+        let document = Document(parsing: source, options: .parseBlockDirectives)
+        let directive = document.child(at: 0) as? BlockDirective
+        XCTAssertNotNil(directive)
+
+        let (bundle, context) = try testBundleAndContext(named: "SampleBundle")
+
+        directive.map { directive in
+            var problems = [Problem]()
+            XCTAssertEqual(Metadata.directiveName, directive.name)
+            let metadata = Metadata(from: directive, source: nil, for: bundle, in: context, problems: &problems)
+            XCTAssertNotNil(metadata)
+            XCTAssertNotNil(metadata?.pageKind)
+            XCTAssertEqual(metadata?.pageKind?.kind, .article)
+            XCTAssert(problems.isEmpty)
+        }
+    }
+}

Tests/SwiftDocCTests/Semantics/DirectiveInfrastructure/DirectiveIndexTests.swift

@@ -37,6 +37,7 @@ class DirectiveIndexTests: XCTestCase {
                 "Metadata",
                 "Options",
                 "PageImage",
+                "PageKind",
                 "Redirected",
                 "Row",
                 "Small",

Tests/SwiftDocCTests/Semantics/DirectiveInfrastructure/DirectiveMirrorTests.swift

@@ -39,7 +39,7 @@ class DirectiveMirrorTests: XCTestCase {
         XCTAssertFalse(reflectedDirective.allowsMarkup)
         XCTAssert(reflectedDirective.arguments.isEmpty)
 
-        XCTAssertEqual(reflectedDirective.childDirectives.count, 7)
+        XCTAssertEqual(reflectedDirective.childDirectives.count, 8)
 
         XCTAssertEqual(
             reflectedDirective.childDirectives["DocumentationExtension"]?.propertyLabel,

Tests/SwiftDocCTests/Test Bundles/SampleBundle.docc/MyLocalSample.md

@@ -2,6 +2,7 @@
 
 @Metadata {
     @CallToAction(file: "Downloads/plus.svg", purpose: download)
+    @PageKind(sampleCode)
 }
 
 Here's a taste of what you can do with my cool framework.

Tests/SwiftDocCTests/Test Bundles/SampleBundle.docc/MySample.md

@@ -2,6 +2,7 @@
 
 @Metadata {
     @CallToAction(url: "https://example.com/sample.zip", purpose: download)
+    @PageKind(article)
 }
 
 Here's a taste of what you can do with my cool framework.