Update documentation and tests

ethan-kusters · ethan-kusters · commit ff69522381e6 · 2022-09-14T16:15:58.000+01:00
diff --git a/Sources/SwiftDocC/Infrastructure/Topic Graph/AutomaticCuration.swift b/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
             }
         }
diff --git a/Sources/SwiftDocC/Model/DocumentationMarkup.swift b/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
diff --git a/Sources/SwiftDocC/Model/DocumentationNode.swift b/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()
     }
diff --git a/Sources/SwiftDocC/Model/Rendering/RenderNode.swift b/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.
diff --git a/Sources/SwiftDocC/Model/Rendering/RenderNodeTranslator.swift b/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
         }
diff --git a/Sources/SwiftDocC/Model/Rendering/TopicsSectionStyle.swift b/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
     }
 }
diff --git a/Sources/SwiftDocC/Semantics/DirectiveInfrastructure/DirectiveIndex.swift b/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] = [
diff --git a/Sources/SwiftDocC/Semantics/Options/AutomaticSeeAlso.swift b/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
     }
     
diff --git a/Sources/SwiftDocC/Semantics/Options/AutomaticTitleHeading.swift b/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
     }
     
diff --git a/Sources/SwiftDocC/Semantics/Options/Options.swift b/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'.")
diff --git a/Sources/SwiftDocC/Semantics/Options/TopicsVisualStyle.swift b/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
     }
     
diff --git a/Tests/SwiftDocCTests/Converter/RenderNodeCodableTests.swift b/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)
diff --git a/Tests/SwiftDocCTests/Model/SemaToRenderNodeTests.swift b/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: """
diff --git a/Tests/SwiftDocCTests/Rendering/AutomaticSeeAlsoTests.swift b/Tests/SwiftDocCTests/Rendering/AutomaticSeeAlsoTests.swift
diff --git a/Tests/SwiftDocCTests/Semantics/DirectiveInfrastructure/DirectiveIndexTests.swift b/Tests/SwiftDocCTests/Semantics/DirectiveInfrastructure/DirectiveIndexTests.swift
diff --git a/Tests/SwiftDocCTests/Semantics/General Purpose Analyses/HasOnlyKnownDirectivesTests.swift b/Tests/SwiftDocCTests/Semantics/General Purpose Analyses/HasOnlyKnownDirectivesTests.swift
diff --git a/Tests/SwiftDocCTests/Semantics/Options/OptionsTests.swift b/Tests/SwiftDocCTests/Semantics/Options/OptionsTests.swift
diff --git a/Tests/SwiftDocCTests/Semantics/RedirectedTests.swift b/Tests/SwiftDocCTests/Semantics/RedirectedTests.swift
diff --git a/Tests/SwiftDocCTests/XCTestCase+LoadingTestData.swift b/Tests/SwiftDocCTests/XCTestCase+LoadingTestData.swift

Original file line number	Diff line number	Diff line change
`@@ -123,8 +123,10 @@ public struct AutomaticCuration {`
`123`	`123`	`renderContext: RenderContext?,`
`124`	`124`	`renderer: DocumentationContentRenderer`
`125`	`125`	`) throws -> TaskGroup? {`
`126`		`- if let automaticSeeAlsoOption = node.options?.automaticSeeAlso ?? context.options?.automaticSeeAlso {`
`127`		`- guard automaticSeeAlsoOption.behavior == .siblingPages else {`
	`126`	`+ if let automaticSeeAlsoOption = node.options?.automaticSeeAlsoBehavior`
	`127`	`+ ?? context.options?.automaticSeeAlsoBehavior`
	`128`	`+ {`
	`129`	`+ guard automaticSeeAlsoOption == .siblingPages else {`
`128`	`130`	`return nil`
`129`	`131`	`}`
`130`	`132`	`}`
Original file line number	Diff line number	Diff line change
`@@ -617,6 +617,7 @@ public struct DocumentationNode {`
`617`	`617`	`self.docChunks = [DocumentationChunk(source: .documentationExtension, markup: articleMarkup)]`
`618`	`618`	`self.markup = articleMarkup`
`619`	`619`	`self.isVirtual = false`
	`620`	`+ self.options = article.options[.local]`
`620`	`621`
`621`	`622`	`updateAnchorSections()`
`622`	`623`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1043,10 +1043,10 @@ public struct RenderNodeTranslator: SemanticVisitor {`
`1043`	`1043`
`1044`	`1044`	`private func shouldCreateAutomaticRoleHeading(for node: DocumentationNode) -> Bool {`
`1045`	`1045`	`var shouldCreateAutomaticRoleHeading = true`
`1046`		`- if let automaticTitleHeadingOption = node.options?.automaticTitleHeading`
`1047`		`- ?? context.options?.automaticTitleHeading`
	`1046`	`+ if let automaticTitleHeadingOption = node.options?.automaticTitleHeadingBehavior`
	`1047`	`+ ?? context.options?.automaticTitleHeadingBehavior`
`1048`	`1048`	`{`
`1049`		`- shouldCreateAutomaticRoleHeading = automaticTitleHeadingOption.behavior == .pageKind`
	`1049`	`+ shouldCreateAutomaticRoleHeading = automaticTitleHeadingOption == .pageKind`
`1050`	`1050`	`}`
`1051`	`1051`
`1052`	`1052`	`return shouldCreateAutomaticRoleHeading`
`@@ -1057,7 +1057,7 @@ public struct RenderNodeTranslator: SemanticVisitor {`
`1057`	`1057`	`if let topicsSectionStyleOption = node.options?.topicsVisualStyle`
`1058`	`1058`	`?? context.options?.topicsVisualStyle`
`1059`	`1059`	`{`
`1060`		`- topicsVisualStyleOption = topicsSectionStyleOption.style`
	`1060`	`+ topicsVisualStyleOption = topicsSectionStyleOption`
`1061`	`1061`	`} else {`
`1062`	`1062`	`topicsVisualStyleOption = .list`
`1063`	`1063`	`}`
Original file line number	Diff line number	Diff line change
`@@ -17,6 +17,7 @@ struct DirectiveIndex {`
`17`	`17`	`Snippet.self,`
`18`	`18`	`DeprecationSummary.self,`
`19`	`19`	`Row.self,`
	`20`	`+ Options.self,`
`20`	`21`	`]`
`21`	`22`
`22`	`23`	`private static let topLevelTutorialDirectives: [AutomaticDirectiveConvertible.Type] = [`