Add support for @Small directive

Adds support for the @Small directive as described here:
https://forums.swift.org/t/supporting-more-dynamic-content-in-swift-docc-reference-documentation/59527#small-18

A new @Small directive based on HTML’s small tag.
This directive can be used to specify small print like legal,
license, or copyright text that should be rendered in a smaller
font size.

@Small accepts no parameters and accepts arbitrary DocC markup body
content.

Example:

    You can create a sloth using the ``init(name:color:power:)``
    initializer, or create randomly generated sloth using a
    ``SlothGenerator``:

       let slothGenerator = MySlothGenerator(seed: randomSeed())
       let habitat = Habitat(isHumid: false, isWarm: true)

       // ...

    @Small {
        Licensed under Apache License v2.0 with Runtime Library Exception
    }

Resolves rdar://97744845

Author: ethan-kusters

Sources/SwiftDocC/Indexing/RenderBlockContent+TextIndexing.swift

@@ -62,6 +62,8 @@ extension RenderBlockContent: TextIndexing {
             return row.columns.map { column in
                 return column.content.rawIndexableTextContent(references: references)
             }.joined(separator: " ")
+        case .small(let small):
+            return small.inlineContent.rawIndexableTextContent(references: references)
         default:
             fatalError("unknown RenderBlockContent case in rawIndexableTextContent")
         }

Sources/SwiftDocC/Model/Rendering/Content/RenderBlockContent.swift

@@ -62,6 +62,8 @@ public enum RenderBlockContent: Equatable {
     case table(Table)
 
     case row(Row)
+    
+    case small(Small)
 
     // Warning: If you add a new case to this enum, make sure to handle it in the Codable
     // conformance at the bottom of this file, and in the `rawIndexableTextContent` method in
@@ -427,6 +429,10 @@ public enum RenderBlockContent: Equatable {
             public let content: [RenderBlockContent]
         }
     }
+    
+    public struct Small: Codable, Equatable {
+        public let inlineContent: [RenderInlineContent]
+    }
 }
 
 // Codable conformance
@@ -489,11 +495,15 @@ extension RenderBlockContent: Codable {
                     columns: container.decode([Row.Column].self, forKey: .columns)
                 )
             )
+        case .small:
+            self = try .small(
+                Small(inlineContent: container.decode([RenderInlineContent].self, forKey: .inlineContent))
+            )
         }
     }
 
     private enum BlockType: String, Codable {
-        case paragraph, aside, codeListing, heading, orderedList, unorderedList, step, endpointExample, dictionaryExample, table, termList, row
+        case paragraph, aside, codeListing, heading, orderedList, unorderedList, step, endpointExample, dictionaryExample, table, termList, row, small
     }
 
     private var type: BlockType {
@@ -510,6 +520,7 @@ extension RenderBlockContent: Codable {
         case .table: return .table
         case .termList: return .termList
         case .row: return .row
+        case .small: return .small
         default: fatalError("unknown RenderBlockContent case in type property")
         }
     }
@@ -559,6 +570,8 @@ extension RenderBlockContent: Codable {
         case .row(let row):
             try container.encode(row.numberOfColumns, forKey: .numberOfColumns)
             try container.encode(row.columns, forKey: .columns)
+        case .small(let small):
+            try container.encode(small.inlineContent, forKey: .inlineContent)
         default:
             fatalError("unknown RenderBlockContent case in encode method")
         }

Sources/SwiftDocC/Semantics/DirectiveInfrastructure/DirectiveIndex.swift

@@ -17,6 +17,7 @@ struct DirectiveIndex {
         Snippet.self,
         DeprecationSummary.self,
         Row.self,
+        Small.self,
     ]
 
     private static let topLevelTutorialDirectives: [AutomaticDirectiveConvertible.Type] = [

Sources/SwiftDocC/Semantics/Reference/Small.swift

@@ -0,0 +1,58 @@
+/*
+ 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
+
+public final class Small: Semantic, AutomaticDirectiveConvertible, MarkupContaining {
+    public let originalMarkup: BlockDirective
+    
+    @ChildMarkup(numberOfParagraphs: .oneOrMore)
+    public private(set) var content: MarkupContainer
+    
+    static var keyPaths: [String : AnyKeyPath] = [
+        "content" : \Small._content,
+    ]
+    
+    override var children: [Semantic] {
+        return [content]
+    }
+    
+    var childMarkup: [Markup] {
+        return content.elements
+    }
+    
+    @available(*, deprecated,
+        message: "Do not call directly. Required for 'AutomaticDirectiveConvertible'."
+    )
+    init(originalMarkup: BlockDirective) {
+        self.originalMarkup = originalMarkup
+    }
+}
+
+extension Small: RenderableDirectiveConvertible {
+    func render(with contentCompiler: inout RenderContentCompiler) -> [RenderContent] {
+        // Render the content normally
+        let renderBlockContent = content.elements.flatMap { markupElement in
+            return contentCompiler.visit(markupElement) as! [RenderBlockContent]
+        }
+        
+        // Transform every paragraph in the render block content to a small paragraph
+        let transformedRenderBlockContent = renderBlockContent.map { block -> RenderBlockContent in
+            guard case let .paragraph(paragraph) = block else {
+                return block
+            }
+            
+            return .small(RenderBlockContent.Small(inlineContent: paragraph.inlineContent))
+        }
+        
+        return transformedRenderBlockContent
+    }
+}

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

@@ -434,6 +434,9 @@
                     {
                         "$ref": "#/components/schemas/Aside"
                     },
+                    {
+                        "$ref": "#/components/schemas/Small"
+                    },
                     {
                         "$ref": "#/components/schemas/Heading"
                     },
@@ -619,6 +622,25 @@
                     }
                 }
             },
+            "Small": {
+                "type": "object",
+                "required": [
+                    "type",
+                    "inlineContent",
+                ],
+                "properties": {
+                    "type": {
+                        "type": "string",
+                        "enum": ["small"]
+                    },
+                    "inlineContent": {
+                        "type": "array",
+                        "items": {
+                            "$ref": "#/components/schemas/RenderInlineContent"
+                        }
+                    }
+                }
+            },
             "Heading": {
                 "type": "object",
                 "required": [