Add authoring support for the @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 inline 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
    }

Dependencies:

- swiftlang/swift-docc-render#405

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

@@ -63,6 +63,9 @@ public enum RenderBlockContent: Equatable {
 
     /// A row in a grid-based layout system that describes a collection of columns.
     case row(Row)
+    
+    /// A paragraph of small print content that should be rendered in a small font.
+    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
@@ -428,6 +431,15 @@ public enum RenderBlockContent: Equatable {
             public let content: [RenderBlockContent]
         }
     }
+    
+    /// A paragraph of small print content that should be rendered in a small font.
+    ///
+    /// Small is based on HTML's `<small>` tag and could contain content like legal,
+    /// license, or copyright text.
+    public struct Small: Codable, Equatable {
+        /// The inline content that should be rendered.
+        public let inlineContent: [RenderInlineContent]
+    }
 }
 
 // Codable conformance
@@ -490,11 +502,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 {
@@ -511,6 +527,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")
         }
     }
@@ -560,6 +577,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

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

Sources/SwiftDocC/Semantics/Reference/Small.swift

@@ -0,0 +1,80 @@
+/*
+ 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 for specifying small print text like legal, license, or copyright text that
+/// should be rendered in a smaller font size.
+///
+/// The `@Small` directive is based on HTML's small tag (`<small>`). It supports any inline markup
+/// formatting like bold and italics but does not support more structured markup like ``Row``
+/// and ``Row/Column``.
+///
+/// ```md
+/// 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._
+/// }
+/// ```
+public final class Small: Semantic, AutomaticDirectiveConvertible, MarkupContaining {
+    public let originalMarkup: BlockDirective
+    
+    /// The inline markup that should be rendered in a small font.
+    @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": [

Tests/SwiftDocCTests/Rendering/RenderNodeTranslatorTests.swift

@@ -1058,4 +1058,37 @@ class RenderNodeTranslatorTests: XCTestCase {
         XCTAssertEqual(row.columns.last?.size, 5)
         XCTAssertEqual(row.columns.last?.content.count, 3)
     }
+    
+    func testSmall() throws {
+        let (bundle, context) = try testBundleAndContext(named: "BookLikeContent")
+        let reference = ResolvedTopicReference(
+            bundleIdentifier: bundle.identifier,
+            path: "/documentation/BestBook/MyArticle",
+            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 discussion = try XCTUnwrap(
+            renderNode.primaryContentSections.first(
+                where: { $0.kind == .content }
+            ) as? ContentRenderSection
+        )
+        
+        guard case let .small(small) = discussion.content.last else {
+            XCTFail("Expected to find small as last child.")
+            return
+        }
+        
+        XCTAssertEqual(
+            small.inlineContent,
+            [.text("Copyright (c) 2022 Apple Inc and the Swift Project authors. All Rights Reserved.")]
+        )
+    }
 }

Tests/SwiftDocCTests/Semantics/DirectiveInfrastructure/DirectiveIndexTests.swift

@@ -33,6 +33,7 @@ class DirectiveIndexTests: XCTestCase {
                 "Options",
                 "Redirected",
                 "Row",
+                "Small",
                 "Snippet",
                 "Stack",
                 "TechnologyRoot",
@@ -50,6 +51,7 @@ class DirectiveIndexTests: XCTestCase {
             DirectiveIndex.shared.renderableDirectives.keys.sorted(),
             [
                 "Row",
+                "Small",
             ]
         )
     }