Add authoring support for @TitleHeading directive (#611) (#623)

A new `@TitleHeading` metadata directive for customizing the text of a page-title heading (also known as an eyebrow or kick). `@TitleHeading` accepts an unnamed parameter containing containing the page-title’s heading text. @metadata { @TitleHeading("Release Notes") } This feature has been pitched on the forums here: https://forums.swift.org/t/supporting-more-types-of-documentation-with-swift-docc/59725#titleheading-10 rdar://110662981
swiftlang · Jun 13, 2023 · 6f72447 · 6f72447
1 parent 08df11b
commit 6f72447
Show file tree

Hide file tree

Showing 15 changed files with 344 additions and 11 deletions.
diff --git a/Sources/SwiftDocC/Infrastructure/External Data/OutOfProcessReferenceResolver.swift b/Sources/SwiftDocC/Infrastructure/External Data/OutOfProcessReferenceResolver.swift
@@ -276,7 +276,7 @@ public class OutOfProcessReferenceResolver: ExternalReferenceResolver, FallbackR
         // with a render node.
 
         if let topicImages = resolvedInformation.topicImages, !topicImages.isEmpty {
-            let metadata = node.metadata ?? Metadata(originalMarkup: BlockDirective(name: "Metadata", children: []), documentationExtension: nil, technologyRoot: nil, displayName: nil)
+            let metadata = node.metadata ?? Metadata(originalMarkup: BlockDirective(name: "Metadata", children: []), documentationExtension: nil, technologyRoot: nil, displayName: nil, titleHeading: nil)
 
             metadata.pageImages = topicImages.map { topicImage in
                 let purpose: PageImage.Purpose

diff --git a/Sources/SwiftDocC/Model/Rendering/RenderNodeTranslator.swift b/Sources/SwiftDocC/Model/Rendering/RenderNodeTranslator.swift
@@ -841,12 +841,16 @@ 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
         }
 
+        if let titleHeading = article.metadata?.titleHeading {
+            node.metadata.roleHeading = titleHeading.heading
+        } 
+
         collectedTopicReferences.append(contentsOf: contentCompiler.collectedTopicReferences)
         node.references = createTopicRenderReferences()
 
@@ -1247,6 +1251,10 @@ public struct RenderNodeTranslator: SemanticVisitor {
         if shouldCreateAutomaticRoleHeading(for: documentationNode) {
             node.metadata.roleHeadingVariants = VariantCollection<String?>(from: symbol.roleHeadingVariants)
         }
+
+        if let titleHeading = documentationNode.metadata?.titleHeading {
+            node.metadata.roleHeadingVariants = VariantCollection<String?>(defaultValue: titleHeading.heading)
+        }
 
         node.metadata.symbolKindVariants = VariantCollection<String?>(from: symbol.kindVariants) { _, kindVariants in
             kindVariants.identifier.renderingIdentifier

diff --git a/Sources/SwiftDocC/Semantics/Article/Article.swift b/Sources/SwiftDocC/Semantics/Article/Article.swift
@@ -218,7 +218,7 @@ public final class Article: Semantic, MarkupConvertible, Abstracted, Redirected,
             problems.append(Problem(diagnostic: diagnostic, possibleSolutions: solutions))
 
             // Remove the display name customization from the article's metadata.
-            optionalMetadata = Metadata(originalMarkup: metadata.originalMarkup, documentationExtension: metadata.documentationOptions, technologyRoot: metadata.technologyRoot, displayName: nil)
+            optionalMetadata = Metadata(originalMarkup: metadata.originalMarkup, documentationExtension: metadata.documentationOptions, technologyRoot: metadata.technologyRoot, displayName: nil, titleHeading: metadata.titleHeading)
         }
 
         self.init(

diff --git a/Sources/SwiftDocC/Semantics/Metadata/Metadata.swift b/Sources/SwiftDocC/Semantics/Metadata/Metadata.swift
@@ -27,6 +27,7 @@ import Markdown
 /// - ``Availability``
 /// - ``PageKind``
 /// - ``SupportedLanguage``
+/// - ``TitleHeading``
 public final class Metadata: Semantic, AutomaticDirectiveConvertible {
     public let originalMarkup: BlockDirective
 
@@ -68,6 +69,9 @@ public final class Metadata: Semantic, AutomaticDirectiveConvertible {
     var pageColor: PageColor.Color? {
         _pageColor?.color
     }
+
+    @ChildDirective
+    var titleHeading: TitleHeading? = nil
 
     static var keyPaths: [String : AnyKeyPath] = [
         "documentationOptions"  : \Metadata._documentationOptions,
@@ -79,20 +83,23 @@ public final class Metadata: Semantic, AutomaticDirectiveConvertible {
         "availability"          : \Metadata._availability,
         "pageKind"              : \Metadata._pageKind,
         "supportedLanguages"    : \Metadata._supportedLanguages,
-        "_pageColor"             : \Metadata.__pageColor,
+        "_pageColor"            : \Metadata.__pageColor,
+        "titleHeading"          : \Metadata._titleHeading,
     ]
 
     /// Creates a metadata object with a given markup, documentation extension, and technology root.
     /// - Parameters:
     ///   - originalMarkup: The original markup for this metadata directive.
     ///   - documentationExtension: Optional configuration that describes how this documentation extension file merges or overrides the in-source documentation.
     ///   - technologyRoot: Optional configuration to make this page root-level documentation.
-    ///   - displayName:Optional configuration to customize this page's symbol's display name.
-    init(originalMarkup: BlockDirective, documentationExtension: DocumentationExtension?, technologyRoot: TechnologyRoot?, displayName: DisplayName?) {
+    ///   - displayName: Optional configuration to customize this page's symbol's display name.
+    ///   - titleHeading: Optional configuration to customize the text of this page's title heading.
+    init(originalMarkup: BlockDirective, documentationExtension: DocumentationExtension?, technologyRoot: TechnologyRoot?, displayName: DisplayName?, titleHeading: TitleHeading?) {
         self.originalMarkup = originalMarkup
         self.documentationOptions = documentationExtension
         self.technologyRoot = technologyRoot
         self.displayName = displayName
+        self.titleHeading = titleHeading
     }
 
     @available(*, deprecated, message: "Do not call directly. Required for 'AutomaticDirectiveConvertible'.")
@@ -102,7 +109,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 && pageKind == nil && pageColor == nil {
+        if documentationOptions == nil && technologyRoot == nil && displayName == nil && pageImages.isEmpty && customMetadata.isEmpty && callToAction == nil && availability.isEmpty && pageKind == nil && pageColor == nil && titleHeading == nil {
             let diagnostic = Diagnostic(
                 source: source,
                 severity: .information,

diff --git a/Sources/SwiftDocC/Semantics/Metadata/TitleHeading.swift b/Sources/SwiftDocC/Semantics/Metadata/TitleHeading.swift
@@ -0,0 +1,41 @@
+/*
+ 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
+
+/// A directive for customizing the text of a page's title heading.
+/// 
+/// The ``heading`` property will override the page's default title heading.
+///
+/// @TitleHeading accepts an unnamed parameter containing containing the page's title heading.
+/// 
+/// This directive is only valid within a top-level ``Metadata`` directive:
+/// ```markdown
+/// @Metadata {
+///    @TitleHeading("Release Notes")
+/// }
+/// ```
+public final class TitleHeading: Semantic, AutomaticDirectiveConvertible {
+    public let originalMarkup: BlockDirective
+
+    /// An unnamed parameter containing containing the page-title’s heading text.
+    @DirectiveArgumentWrapped(name: .unnamed)
+    public var heading: String
+
+    static var keyPaths: [String : AnyKeyPath] = [
+        "heading" : \TitleHeading._heading,
+    ]
+
+    @available(*, deprecated, message: "Do not call directly. Required for 'AutomaticDirectiveConvertible'.")
+    init(originalMarkup: BlockDirective) {
+        self.originalMarkup = originalMarkup
+    }
+}
diff --git a/Sources/docc/DocCDocumentation.docc/DocC.symbols.json b/Sources/docc/DocCDocumentation.docc/DocC.symbols.json
@@ -2963,6 +2963,9 @@
           },
           {
             "text" : "- ``SupportedLanguage``"
+          },
+          {
+            "text" : "- ``TitleHeading``"
           }
         ]
       },
@@ -5058,6 +5061,151 @@
         "TechnologyRoot"
       ]
     },
+    {
+      "accessLevel" : "public",
+      "declarationFragments" : [
+        {
+          "kind" : "typeIdentifier",
+          "spelling" : "@"
+        },
+        {
+          "kind" : "typeIdentifier",
+          "spelling" : "TitleHeading"
+        },
+        {
+          "kind" : "text",
+          "spelling" : "("
+        },
+        {
+          "kind" : "text",
+          "spelling" : "_ "
+        },
+        {
+          "kind" : "identifier",
+          "spelling" : "heading"
+        },
+        {
+          "kind" : "text",
+          "spelling" : ": "
+        },
+        {
+          "kind" : "typeIdentifier",
+          "spelling" : "String"
+        },
+        {
+          "kind" : "text",
+          "spelling" : ")"
+        }
+      ],
+      "docComment" : {
+        "lines" : [
+          {
+            "text" : "A directive for customizing the text of a page's title heading."
+          },
+          {
+            "text" : ""
+          },
+          {
+            "text" : "The ``heading`` property will override the page's default title heading."
+          },
+          {
+            "text" : ""
+          },
+          {
+            "text" : "@TitleHeading accepts an unnamed parameter containing containing the page's title heading."
+          },
+          {
+            "text" : ""
+          },
+          {
+            "text" : "This directive is only valid within a top-level ``Metadata`` directive:"
+          },
+          {
+            "text" : "```markdown"
+          },
+          {
+            "text" : "@Metadata {"
+          },
+          {
+            "text" : "   @TitleHeading(\"Release Notes\")"
+          },
+          {
+            "text" : "}"
+          },
+          {
+            "text" : "```"
+          },
+          {
+            "text" : "- Parameters:"
+          },
+          {
+            "text" : "  - heading: An unnamed parameter containing containing the page-title’s heading text."
+          },
+          {
+            "text" : "     **(required)**"
+          }
+        ]
+      },
+      "identifier" : {
+        "interfaceLanguage" : "swift",
+        "precise" : "__docc_universal_symbol_reference_$TitleHeading"
+      },
+      "kind" : {
+        "displayName" : "Directive",
+        "identifier" : "class"
+      },
+      "names" : {
+        "navigator" : [
+          {
+            "kind" : "attribute",
+            "spelling" : "@"
+          },
+          {
+            "kind" : "identifier",
+            "preciseIdentifier" : "__docc_universal_symbol_reference_$TitleHeading",
+            "spelling" : "TitleHeading"
+          }
+        ],
+        "subHeading" : [
+          {
+            "kind" : "identifier",
+            "spelling" : "@"
+          },
+          {
+            "kind" : "identifier",
+            "spelling" : "TitleHeading"
+          },
+          {
+            "kind" : "text",
+            "spelling" : "("
+          },
+          {
+            "kind" : "text",
+            "spelling" : "_ "
+          },
+          {
+            "kind" : "identifier",
+            "spelling" : "heading"
+          },
+          {
+            "kind" : "text",
+            "spelling" : ": "
+          },
+          {
+            "kind" : "typeIdentifier",
+            "spelling" : "String"
+          },
+          {
+            "kind" : "text",
+            "spelling" : ")"
+          }
+        ],
+        "title" : "TitleHeading"
+      },
+      "pathComponents" : [
+        "TitleHeading"
+      ]
+    },
     {
       "accessLevel" : "public",
       "declarationFragments" : [

diff --git a/...s/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/Metadata.md b/...s/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/Metadata.md
@@ -30,6 +30,16 @@ Use the `Metadata` directive with the ``DisplayName`` directive to configure a s
 }
 ```
 
+Use the `Metadata` directive with the ``TitleHeading`` directive to configure the text of a page's title heading.
+
+```
+# ``SlothCreator``
+
+@Metadata {
+    @TitleHeading("Release Notes")
+}
+```
+
 ## Topics
 
 ### Extending or Overriding Source Documentation
@@ -47,6 +57,7 @@ Use the `Metadata` directive with the ``DisplayName`` directive to configure a s
 - ``PageKind``
 - ``PageColor``
 - ``CallToAction``
+- ``TitleHeading``
 
 ### Customizing the Languages of an Article
 

diff --git a/...cc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/TitleHeading.md b/...cc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/TitleHeading.md
@@ -0,0 +1,35 @@
+# ``docc/TitleHeading``
+
+A directive that specifies a title heading for a given documentation page.
+
+@Metadata {
+    @DocumentationExtension(mergeBehavior: override)
+}
+
+- Parameters:
+    - heading: The text for the custom title heading.
+
+## Overview
+
+Place the `TitleHeading` directive within a `Metadata` directive to configure a documentation page to show a custom title heading. Custom title headings, along with custom [page icons](doc:PageImage) and [page colors](doc:PageColor), allow for the creation of custom kinds of pages beyond just articles.
+
+A title heading is also known as a page eyebrow or kicker.
+
+```
+# ``SlothCreator``
+
+@Metadata {
+    @TitleHeading("Release Notes")
+}
+```
+
+A custom title heading appears in place of the page kind at the top of the page.
+### Containing Elements
+
+The following items can include a title heading element:
+
+@Links(visualStyle: list) {
+   - ``Metadata``
+}
+
+<!-- Copyright (c) 2023 Apple Inc and the Swift Project authors. All Rights Reserved. -->
diff --git a/Tests/SwiftDocCTests/Infrastructure/TestExternalReferenceResolvers.swift b/Tests/SwiftDocCTests/Infrastructure/TestExternalReferenceResolvers.swift
@@ -159,7 +159,7 @@ class TestMultiResultExternalReferenceResolver: ExternalReferenceResolver, Fallb
         // This is a workaround for how external content is processed. See details in OutOfProcessReferenceResolver.addImagesAndCacheMediaReferences(to:from:)
 
         if let topicImages = entityInfo.topicImages {
-            let metadata = node.metadata ?? Metadata(originalMarkup: BlockDirective(name: "Metadata", children: []), documentationExtension: nil, technologyRoot: nil, displayName: nil)
+            let metadata = node.metadata ?? Metadata(originalMarkup: BlockDirective(name: "Metadata", children: []), documentationExtension: nil, technologyRoot: nil, displayName: nil, titleHeading: nil)
 
             metadata.pageImages = topicImages.map { topicImage, alt in
                 let purpose: PageImage.Purpose