Support for custommetadata (#405)

rdar://97739617 (Add a directive for custom page metadata (@CustomMetadata))

Author: binamaniar

Sources/SwiftDocC/Model/Rendering/RenderNode/RenderMetadata.swift

@@ -77,6 +77,9 @@ public struct RenderMetadata: VariantContainer {
     /// Authors can use the `@PageImage` metadata directive to provide custom icon and card images for a page.
     public var images: [TopicImage] = []
 
+    /// Author provided custom metadata describing the page.
+    public var customMetadata: [String: String] = [:]
+    
     /// The title of the page.
     public var title: String? {
         get { getVariantDefaultValue(keyPath: \.titleVariants) }
@@ -228,6 +231,7 @@ extension RenderMetadata: Codable {
         public static let remoteSource = CodingKeys(stringValue: "remoteSource")
         public static let tags = CodingKeys(stringValue: "tags")
         public static let images = CodingKeys(stringValue: "images")
+        public static let customMetadata = CodingKeys(stringValue: "customMetadata")
     }
 
     public init(from decoder: Decoder) throws {
@@ -243,6 +247,7 @@ extension RenderMetadata: Codable {
         requiredVariants = try container.decodeVariantCollectionIfPresent(ofValueType: Bool.self, forKey: .required) ?? .init(defaultValue: false)
         roleHeadingVariants = try container.decodeVariantCollectionIfPresent(ofValueType: String?.self, forKey: .roleHeading)
         images = try container.decodeIfPresent([TopicImage].self, forKey: .images) ?? []
+        customMetadata = try container.decodeIfPresent([String: String].self, forKey: .customMetadata) ?? [:]
         let rawRole = try container.decodeIfPresent(String.self, forKey: .role)
         role = rawRole == "tutorial" ? Role.tutorial.rawValue : rawRole
         titleVariants = try container.decodeVariantCollectionIfPresent(ofValueType: String?.self, forKey: .title)
@@ -316,5 +321,6 @@ extension RenderMetadata: Codable {
         }
 
         try container.encodeIfNotEmpty(images, forKey: .images)
+        try container.encodeIfNotEmpty(customMetadata, forKey: .customMetadata)
     }
 }

Sources/SwiftDocC/Model/Rendering/RenderNodeTranslator.swift

@@ -424,6 +424,7 @@ public struct RenderNodeTranslator: SemanticVisitor {
                 imageReferences[imageReference.identifier.identifier] = imageReference
             }
 
+            
             for dependencyReference in dependencies.topicReferences {
                 var dependencyRenderReference: TopicRenderReference
                 if let renderContext = renderContext, let prerendered = renderContext.store.content(for: dependencyReference)?.renderReference as? TopicRenderReference {
@@ -729,6 +730,14 @@ public struct RenderNodeTranslator: SemanticVisitor {
             }
         }
 
+        var metadataCustomDictionary : [String: String] = [:]
+        if let customMetadatas = documentationNode.metadata?.customMetadata {
+            for elem in customMetadatas {
+                metadataCustomDictionary[elem.key] = elem.value
+            }
+        }
+
+        node.metadata.customMetadata = metadataCustomDictionary
         node.seeAlsoSectionsVariants = VariantCollection<[TaskGroupRenderSection]>(
             from: documentationNode.availableVariantTraits,
             fallbackDefaultValue: []
@@ -1171,7 +1180,15 @@ public struct RenderNodeTranslator: SemanticVisitor {
                 )
             }
         }
-        
+
+        var metadataCustomDictionary : [String: String] = [:]
+        if let customMetadatas = documentationNode.metadata?.customMetadata {
+            for elem in customMetadatas {
+                metadataCustomDictionary[elem.key] = elem.value
+            }
+        }
+
+        node.metadata.customMetadata = metadataCustomDictionary
         node.variants = variants(for: documentationNode)
 
         collectedTopicReferences.append(identifier)

Sources/SwiftDocC/Semantics/Metadata/CustomMetadata.swift

@@ -0,0 +1,49 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2022 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 that accepts an arbitary key/valye pair and emits it into the metadata of the page
+///
+/// It accepts following parameters:
+///
+/// key- a key to identify a piece of metadata
+/// value- the value for the metadata
+///
+/// This directive is only valid within a ``Metadata`` directive:
+/// ```
+/// @Metadata {
+///    @CustomMetadata(key: "country", value: "Belgium")
+/// }
+/// ```
+public final class CustomMetadata: Semantic, AutomaticDirectiveConvertible {
+    public let originalMarkup: BlockDirective
+    
+    /// A key to identify a piece of metadata
+    @DirectiveArgumentWrapped
+    public var key: String
+    
+    /// value of the metadata
+    @DirectiveArgumentWrapped
+    public var value: String
+    
+    static var keyPaths: [String : AnyKeyPath] = [
+        "key" : \CustomMetadata._key,
+        "value"  : \CustomMetadata._value,
+    ]
+    
+
+    @available(*, deprecated, message: "Do not call directly. Required for 'AutomaticDirectiveConvertible'.")
+    init(originalMarkup: BlockDirective) {
+        self.originalMarkup = originalMarkup
+    }
+}
+

Sources/SwiftDocC/Semantics/Metadata/Metadata.swift

@@ -40,11 +40,15 @@ public final class Metadata: Semantic, AutomaticDirectiveConvertible {
     @ChildDirective(requirements: .zeroOrMore)
     var pageImages: [PageImage]
 
+    @ChildDirective(requirements: .zeroOrMore)
+    var customMetadata: [CustomMetadata]
+    
     static var keyPaths: [String : AnyKeyPath] = [
         "documentationOptions"  : \Metadata._documentationOptions,
         "technologyRoot"        : \Metadata._technologyRoot,
         "displayName"           : \Metadata._displayName,
         "pageImages"            : \Metadata._pageImages,
+        "customMetadata"        : \Metadata._customMetadata,
     ]
 
     /// Creates a metadata object with a given markup, documentation extension, and technology root.
@@ -67,7 +71,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 {
+        if documentationOptions == nil && technologyRoot == nil && displayName == nil && pageImages.isEmpty && customMetadata.isEmpty {
             let diagnostic = Diagnostic(
                 source: source,
                 severity: .information,

Sources/SwiftDocC/SwiftDocC.docc/Resources/RenderNode.spec.json

@@ -2248,6 +2248,13 @@
                             "$ref": "#/components/schemas/TopicImage"
                         }
                     },
+                    "customMetadata": {
+                        "type": "object",
+                        "description" : "A dictionary containing arbitrary, user-provided metadata key/value pairs.\n\nThese values are authored using the `@CustomMetadata(key:value:)` directive.",
+                        "additionalProperties": {
+                            "type": "string"
+                        }
+                    },
                     "modules": {
                         "type": "array",
                         "items": {

Tests/SwiftDocCTests/Rendering/RenderNodeTranslatorTests.swift

@@ -1169,7 +1169,8 @@ class RenderNodeTranslatorTests: XCTestCase {
          let roundTrippedArticle = try JSONDecoder().decode(RenderNode.self, from: encodedArticle)
 
          XCTAssertEqual(roundTrippedArticle.icon?.identifier, "plus.svg")
-    
+
+         XCTAssertEqual(renderNode.metadata.customMetadata.count, 1)
          XCTAssertEqual(
              roundTrippedArticle.references["figure1.png"] as? ImageReference,
              ImageReference(
@@ -1213,5 +1214,11 @@ class RenderNodeTranslatorTests: XCTestCase {
                  TopicImage(type: .card, identifier: RenderReferenceIdentifier("figure1.png"))
              ]
          )
+
+        XCTAssertEqual(roundTrippedArticle.metadata.customMetadata.count, 1)
+        XCTAssertEqual(roundTrippedArticle.metadata.customMetadata.keys.count, 1)
+        XCTAssertEqual(roundTrippedArticle.metadata.customMetadata.keys.first, "country")
+        XCTAssertEqual(roundTrippedArticle.metadata.customMetadata.values.count, 1)
+        XCTAssertEqual(roundTrippedArticle.metadata.customMetadata.values.first, "Belgium")
      }
 }

Tests/SwiftDocCTests/Semantics/DirectiveInfrastructure/DirectiveIndexTests.swift

@@ -23,6 +23,7 @@ class DirectiveIndexTests: XCTestCase {
                 "Chapter",
                 "Choice",
                 "Column",
+                "CustomMetadata",
                 "DeprecationSummary",
                 "DisplayName",
                 "DocumentationExtension",

Tests/SwiftDocCTests/Semantics/DirectiveInfrastructure/DirectiveMirrorTests.swift

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

Tests/SwiftDocCTests/Semantics/MetadataTests.swift

@@ -131,6 +131,23 @@ class MetadataTests: XCTestCase {
         XCTAssertEqual(metadata?.displayName?.name, "Custom Name")
     }
 
+    func testCustomMetadataSupport() throws {
+        let source = """
+        @Metadata {
+           @CustomMetadata(key: "country", value: "Belgium")
+           @CustomMetadata(key: "continent", value: "Europe")
+        }
+        """
+        let document = Document(parsing: source, options: .parseBlockDirectives)
+        let directive = document.child(at: 0)! as! BlockDirective
+        let (bundle, context) = try testBundleAndContext(named: "TestBundle")
+        var problems = [Problem]()
+        let metadata = Metadata(from: directive, source: nil, for: bundle, in: context, problems: &problems)
+        XCTAssertNotNil(metadata)
+        XCTAssertEqual(metadata?.customMetadata.count, 2)
+        XCTAssertEqual(problems.count, 0)
+    }
+    
     // MARK: - Metadata Support
 
     func testArticleSupportsMetadata() throws {
@@ -319,3 +336,4 @@ class MetadataTests: XCTestCase {
         return (problemIDs, metadata)
     }
 }
+ 

Tests/SwiftDocCTests/Test Bundles/BookLikeContent.docc/MyArticle.md

@@ -5,6 +5,7 @@ This is the abstract of my article. Nice!
 @Metadata {
     @PageImage(source: "plus", alt: "A plus icon.", purpose: icon)
     @PageImage(source: "figure1", alt: "An example figure.", purpose: card)
+    @CustomMetadata(key: "country", value: "Belgium")
 }
 
 @Row(numberOfColumns: 8) {