Update documentation and tests

Author: ethan-kusters

Sources/SwiftDocC/Infrastructure/Topic Graph/AutomaticCuration.swift

@@ -123,8 +123,10 @@ public struct AutomaticCuration {
         renderContext: RenderContext?,
         renderer: DocumentationContentRenderer
     ) throws -> TaskGroup? {
-        if let automaticSeeAlsoOption = node.options?.automaticSeeAlso ?? context.options?.automaticSeeAlso {
-            guard automaticSeeAlsoOption.behavior == .siblingPages else {
+        if let automaticSeeAlsoOption = node.options?.automaticSeeAlsoBehavior
+            ?? context.options?.automaticSeeAlsoBehavior
+        {
+            guard automaticSeeAlsoOption == .siblingPages else {
                 return nil
             }
         }

Sources/SwiftDocC/Model/DocumentationMarkup.swift

@@ -146,7 +146,7 @@ struct DocumentationMarkup {
                         // Found deprecation notice in the abstract.
                         deprecation = MarkupContainer(directive.children)
                         return
-                    } else if directive.name == Comment.directiveName || directive.name == Metadata.directiveName {
+                    } else if directive.name == Comment.directiveName || directive.name == Metadata.directiveName || directive.name == Options.directiveName {
                         // These directives don't affect content so they shouldn't break us out of
                         // the automatic abstract section.
                         return

Sources/SwiftDocC/Model/DocumentationNode.swift

@@ -617,6 +617,7 @@ public struct DocumentationNode {
         self.docChunks = [DocumentationChunk(source: .documentationExtension, markup: articleMarkup)]
         self.markup = articleMarkup
         self.isVirtual = false
+        self.options = article.options[.local]
 
         updateAnchorSections()
     }

Sources/SwiftDocC/Model/Rendering/RenderNode.swift

@@ -162,6 +162,7 @@ public struct RenderNode: VariantContainer {
     /// The variants of the primary content sections of the node, which are the main sections of a reference documentation node.
     public var primaryContentSectionsVariants: [VariantCollection<CodableContentSection?>] = []
 
+    /// The visual style that should be used when rendering this page's Topics section.
     public var topicSectionsStyle: TopicsSectionStyle
 
     /// The default Topics sections of this documentation node, which contain links to useful related documentation nodes.

Sources/SwiftDocC/Model/Rendering/RenderNodeTranslator.swift

@@ -1043,10 +1043,10 @@ public struct RenderNodeTranslator: SemanticVisitor {
 
     private func shouldCreateAutomaticRoleHeading(for node: DocumentationNode) -> Bool {
         var shouldCreateAutomaticRoleHeading = true
-        if let automaticTitleHeadingOption = node.options?.automaticTitleHeading
-            ?? context.options?.automaticTitleHeading
+        if let automaticTitleHeadingOption = node.options?.automaticTitleHeadingBehavior
+            ?? context.options?.automaticTitleHeadingBehavior
         {
-            shouldCreateAutomaticRoleHeading = automaticTitleHeadingOption.behavior == .pageKind
+            shouldCreateAutomaticRoleHeading = automaticTitleHeadingOption == .pageKind
         }
 
         return shouldCreateAutomaticRoleHeading
@@ -1057,7 +1057,7 @@ public struct RenderNodeTranslator: SemanticVisitor {
         if let topicsSectionStyleOption = node.options?.topicsVisualStyle
             ?? context.options?.topicsVisualStyle
         {
-            topicsVisualStyleOption = topicsSectionStyleOption.style
+            topicsVisualStyleOption = topicsSectionStyleOption
         } else {
             topicsVisualStyleOption = .list
         }

Sources/SwiftDocC/Model/Rendering/TopicsSectionStyle.swift

@@ -11,9 +11,20 @@
 extension RenderNode {
     /// The rendering style of the topics section.
     public enum TopicsSectionStyle: String, Codable {
+        /// A list of the page's topics, including their full declaration and abstract.
         case list
+        
+        /// A grid of items based on the card image for each page.
+        ///
+        /// Includes each page’s title and card image but excludes their abstracts.
         case compactGrid
+        
+        /// A grid of items based on the card image for each page.
+        ///
+        /// Unlike ``compactGrid``, this style includes the abstract for each page.
         case detailedGrid
+        
+        /// Do not show child pages anywhere on the page.
         case hidden
     }
 }

Sources/SwiftDocC/Semantics/DirectiveInfrastructure/DirectiveIndex.swift

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

Sources/SwiftDocC/Semantics/Options/AutomaticSeeAlso.swift

@@ -11,15 +11,21 @@
 import Foundation
 import Markdown
 
+/// A directive for specifying Swift-DocC's automatic behavior when generating a page's
+/// See Also section.
 public class AutomaticSeeAlso: Semantic, AutomaticDirectiveConvertible {
     public let originalMarkup: BlockDirective
 
+    /// The specified behavior for automatic See Also section generation.
     @DirectiveArgumentWrapped(name: .unnamed)
     public private(set) var behavior: Behavior
 
+    /// A behavior for automatic See Also section generation.
     public enum Behavior: String, CaseIterable, DirectiveArgumentValueConvertible {
+        /// A See Also section will not be automatically created.
         case disabled
 
+        /// A See Also section will be automatically created based on the page's siblings.
         case siblingPages
     }
 

Sources/SwiftDocC/Semantics/Options/AutomaticTitleHeading.swift

@@ -11,15 +11,23 @@
 import Foundation
 import Markdown
 
+/// A directive for specifying Swift-DocC's automatic behavior when generating a page's
+/// title heading.
+///
+/// A title heading is also known as a page eyebrow or kicker.
 public class AutomaticTitleHeading: Semantic, AutomaticDirectiveConvertible {
     public let originalMarkup: BlockDirective
 
+    /// The specified behavior for automatic title heading generation.
     @DirectiveArgumentWrapped(name: .unnamed)
     public private(set) var behavior: Behavior
 
+    /// A behavior for automatic title heading generation.
     public enum Behavior: String, CaseIterable, DirectiveArgumentValueConvertible {
+        /// No title heading should be created for the page.
         case disabled
 
+        /// A title heading based on the page's kind should be automatically created.
         case pageKind
     }
 

Sources/SwiftDocC/Semantics/Options/Options.swift

@@ -11,32 +11,53 @@
 import Foundation
 import Markdown
 
+/// A directive that specifies various options for the page.
 public class Options: Semantic, AutomaticDirectiveConvertible {
     public let originalMarkup: BlockDirective
 
+    /// Whether the options in this Options directive should apply locally to the page
+    /// or globally to the DocC catalog.
     @DirectiveArgumentWrapped
     public private(set) var scope: Scope = .local
 
     @ChildDirective
-    public private(set) var automaticSeeAlso: AutomaticSeeAlso? = nil
+    public private(set) var _automaticSeeAlso: AutomaticSeeAlso? = nil
 
     @ChildDirective
-    public private(set) var automaticTitleHeading: AutomaticTitleHeading? = nil
+    public private(set) var _automaticTitleHeading: AutomaticTitleHeading? = nil
 
     @ChildDirective
-    public private(set) var topicsVisualStyle: TopicsVisualStyle? = nil
+    public private(set) var _topicsVisualStyle: TopicsVisualStyle? = nil
 
+    /// If given, the authored behavior for automatic See Also section generation.
+    public var automaticSeeAlsoBehavior: AutomaticSeeAlso.Behavior? {
+        return _automaticSeeAlso?.behavior
+    }
+    
+    /// If given, the authored behavior for automatic Title Heading generation.
+    public var automaticTitleHeadingBehavior: AutomaticTitleHeading.Behavior? {
+        return _automaticTitleHeading?.behavior
+    }
+    
+    /// If given, the authored style for a page's Topics section.
+    public var topicsVisualStyle: TopicsVisualStyle.Style? {
+        return _topicsVisualStyle?.style
+    }
+    
+    /// A scope for the options provided by an Options directive.
     public enum Scope: String, CaseIterable, DirectiveArgumentValueConvertible {
+        /// The directive should only affect the current page.
         case local
 
+        /// The directive should affect all pages in the current DocC catalog.
         case global
     }
 
     static var keyPaths: [String : AnyKeyPath] = [
         "scope"                 : \Options._scope,
-        "automaticSeeAlso"      : \Options._automaticSeeAlso,
-        "automaticTitleHeading" : \Options._automaticTitleHeading,
-        "topicsVisualStyle"     : \Options._topicsVisualStyle,
+        "_automaticSeeAlso"      : \Options.__automaticSeeAlso,
+        "_automaticTitleHeading" : \Options.__automaticTitleHeading,
+        "_topicsVisualStyle"     : \Options.__topicsVisualStyle,
     ]
 
     @available(*, deprecated, message: "Do not call directly. Required for 'AutomaticDirectiveConvertible'.")

Sources/SwiftDocC/Semantics/Options/TopicsVisualStyle.swift

@@ -11,16 +11,31 @@
 import Foundation
 import Markdown
 
+/// A directive for specifying the style that should be used when rendering a page's
+/// Topics section.
 public class TopicsVisualStyle: Semantic, AutomaticDirectiveConvertible {
     public let originalMarkup: BlockDirective
 
+    /// The specified style that should be used when rendering a page's Topics section.
     @DirectiveArgumentWrapped(name: .unnamed)
     public private(set) var style: Style
 
+    /// A visual style for a page's Topics section.
     public enum Style: String, CaseIterable, DirectiveArgumentValueConvertible {
+        /// A list of the page's topics, including their full declaration and abstract.
         case list
+        
+        /// A grid of items based on the card image for each page.
+        ///
+        /// Includes each page’s title and card image but excludes their abstracts.
         case compactGrid
+        
+        /// A grid of items based on the card image for each page.
+        ///
+        /// Unlike ``compactGrid``, this style includes the abstract for each page.
         case detailedGrid
+        
+        /// Do not show child pages anywhere on the page.
         case hidden
     }
 

Tests/SwiftDocCTests/Converter/RenderNodeCodableTests.swift

@@ -10,6 +10,7 @@
 
 import XCTest
 @testable import SwiftDocC
+import Markdown
 
 class RenderNodeCodableTests: XCTestCase {
 
@@ -158,6 +159,70 @@ class RenderNodeCodableTests: XCTestCase {
         }
     }
 
+    func testDecodeRenderNodeWithoutTopicSectionStyle() throws {
+        let exampleRenderNodeJSON = Bundle.module.url(
+            forResource: "Operator",
+            withExtension: "json",
+            subdirectory: "Test Resources"
+        )!
+        
+        let renderNodeData = try Data(contentsOf: exampleRenderNodeJSON)
+        
+        let renderNode = try JSONDecoder().decode(RenderNode.self, from: renderNodeData)
+        XCTAssertEqual(renderNode.topicSectionsStyle, .list)
+    }
+    
+    func testEncodeRenderNodeWithCustomTopicSectionStyle() throws {
+        let (bundle, context) = try testBundleAndContext()
+        var problems = [Problem]()
+        
+        let source = """
+            # My Great Article
+            
+            A great article.
+            
+            @Options {
+                @TopicsVisualStyle(compactGrid)
+            }
+            """
+        
+        let document = Document(parsing: source, options: .parseBlockDirectives)
+        let article = try XCTUnwrap(
+            Article(from: document.root, source: nil, for: bundle, in: context, problems: &problems)
+        )
+        
+        let reference = ResolvedTopicReference(
+            bundleIdentifier: "org.swift.docc.example",
+            path: "/documentation/test/customTopicSectionStyle",
+            fragment: nil,
+            sourceLanguage: .swift
+        )
+        context.documentationCache[reference] = try DocumentationNode(reference: reference, article: article)
+        let topicGraphNode = TopicGraph.Node(
+            reference: reference,
+            kind: .article,
+            source: .file(url: URL(fileURLWithPath: "/path/to/article.md")),
+            title: "My Article"
+        )
+        context.topicGraph.addNode(topicGraphNode)
+        
+        var translator = RenderNodeTranslator(
+            context: context,
+            bundle: bundle,
+            identifier: reference,
+            source: nil
+        )
+        let node = try XCTUnwrap(translator.visitArticle(article) as? RenderNode)
+        XCTAssertEqual(node.topicSectionsStyle, .compactGrid)
+        
+        let encoder = JSONEncoder()
+        let decoder = JSONDecoder()
+        
+        let encodedNode = try encoder.encode(node)
+        let decodedNode = try decoder.decode(RenderNode.self, from: encodedNode)
+        XCTAssertEqual(decodedNode.topicSectionsStyle, .compactGrid)
+    }
+    
     private func assertVariantOverrides(_ variantOverrides: VariantOverrides) throws {
         XCTAssertEqual(variantOverrides.values.count, 1)
         let variantOverride = try XCTUnwrap(variantOverrides.values.first)

Tests/SwiftDocCTests/Model/SemaToRenderNodeTests.swift

@@ -1782,6 +1782,32 @@ Document @1:1-11:19
             """
         )
     }
+    
+    func testArticleRoleHeadingsWithAutomaticTitleHeadingDisabled() throws {
+        try assertRoleHeadingForArticleInTestBundle(expectedRoleHeading: nil, content: """
+            # Article 2
+            
+            @Options {
+                @AutomaticTitleHeading(disabled)
+            }
+
+            This is article 2.
+            """
+        )
+    }
+    
+    func testArticleRoleHeadingsWithAutomaticTitleHeadingForPageKind() throws {
+        try assertRoleHeadingForArticleInTestBundle(expectedRoleHeading: "Article", content: """
+            # Article 2
+            
+            @Options {
+                @AutomaticTitleHeading(pageKind)
+            }
+
+            This is article 2.
+            """
+        )
+    }
 
     func testAPICollectionRoleHeading() throws {
         try assertRoleHeadingForArticleInTestBundle(expectedRoleHeading: nil, content: """