Add support for @Options directive (#368)

- Adds a new `@Options` directive for holding other directives describing how
  content on the local page should be autogenerated and rendered.

  This directive functions like the existing `@Metadata` directive but is used
  specifically for "option directives" that effect the way content is rendered
  on the page (and not the content itself).

  Any directive that can be used in `@Options` is called an "option directive".

  The `@Options` directive accepts a `scope` parameter of either `local` or
  `global`.  A `local` scoped `@Options` affects only the current page while a
  `global` scoped one affects the entire DocC catalog.

  Example:

    @options(scope: global) {
      @AutomaticTitleHeading(disabled)
    }

    @options {
      @AutomaticSeeAlso(disabled)
      @TopicsVisualStyle(detailedGrid)
    }

  `@Options` is described on the Swift forums here:
  https://forums.swift.org/t/supporting-more-types-of-documentation-with-swift-docc/59725#options-1

-------------------------------------------------------------------------------

- Adds a new `@AutomaticTitleHeading` option directive for customizing the way a
  page-title’s heading (also known as an eyebrow or kicker) is automatically
  generated.

  `@AutomaticTitleHeading` accepts an unnamed parameter of either `pageKind`
  or `disabled`.

  - `pageKind`: A page-title heading will be automatically added based on the
    page’s kind. This is Swift-DocC’s current default if no automatic subheading
    generation style is specified.

  - `disabled`: A page-title heading will not be automatically created for the
    page.

  `@AutomaticTitleHeading` is described on the Swift forums here:
  https://forums.swift.org/t/supporting-more-types-of-documentation-with-swift-docc/59725#automatictitleheading-4

-------------------------------------------------------------------------------

- Adds a new `@AutomaticSeeAlso` option directive for customizing the way
  See Also sections are automatically generated on a given page.

  `@AutomaticSeeAlso` accepts an unnamed parameter containing one of the following:

  - `siblingPages`: The current list of auto-generated “See Also” items based
    on sibling items. This is Swift-DocC’s current default if an automatic
    see also style is not specified.

  - `disabled`: Do not automatically generate any See Also items.

`@AutomaticSeeAlso` is described on the Swift forums here:
https://forums.swift.org/t/supporting-more-types-of-documentation-with-swift-docc/59725#automaticseealso-14

-------------------------------------------------------------------------------

- Adds a new `@TopicsVisualStyle` option directive for customizing the way
  Topics sections are rendered on a given page.

  `@TopicsVisualStyle` accepts an unnamed parameter containing one of the
  following:

  - `list`: The current list of topics we render on page, including their
    abstracts. This is Swift-DocC’s current default if a topics style is
    not specified.

  - `compactGrid`: A grid of items based on the card image for each page.
    Includes each page’s title and card image but excludes their abstracts.

  - `detailedGrid`: A grid of items based on the card image for each page,
    includes the abstract for each page.

  - `hidden`: Don’t show child pages anywhere on the page.

`@TopicsVisualStyle` is described on the Swift forums here:
https://forums.swift.org/t/supporting-more-types-of-documentation-with-swift-docc/59725#topicsvisualstyle-18

-------------------------------------------------------------------------------

Resolves rdar://97737541

Author: ethan-kusters

Sources/SwiftDocC/Infrastructure/DocumentationContext.swift

@@ -127,6 +127,9 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
 
     /// The graph of all the documentation content and their relationships to each other.
     var topicGraph = TopicGraph()
+    
+    /// User-provided global options for this documentation conversion.
+    var options: Options?
 
     /// A value to control whether the set of manually curated references found during bundle registration should be stored. Defaults to `false`. Setting this property to `false` clears any stored references from `manuallyCuratedReferences`.
     public var shouldStoreManuallyCuratedReferences: Bool = false {
@@ -1981,6 +1984,43 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
         let (technologies, tutorials, tutorialArticles, allArticles) = result
         var (otherArticles, rootPageArticles) = splitArticles(allArticles)
 
+        let globalOptions = (allArticles + uncuratedDocumentationExtensions.values.flatMap { $0 }).compactMap { article in
+            return article.value.options[.global]
+        }
+        
+        if globalOptions.count > 1 {
+            let extraGlobalOptionsProblems = globalOptions.map { extraOptionsDirective -> Problem in
+                let diagnostic = Diagnostic(
+                    source: extraOptionsDirective.originalMarkup.nameLocation?.source,
+                    severity: .warning,
+                    range: extraOptionsDirective.originalMarkup.range,
+                    identifier: "org.swift.docc.DuplicateGlobalOptions",
+                    summary: "Duplicate \(extraOptionsDirective.scope) \(Options.directiveName.singleQuoted) directive",
+                    explanation: """
+                    A DocC catalog can only contain a single \(Options.directiveName.singleQuoted) \
+                    directive with the \(extraOptionsDirective.scope.rawValue.singleQuoted) scope.
+                    """
+                )
+                
+                guard let range = extraOptionsDirective.originalMarkup.range else {
+                    return Problem(diagnostic: diagnostic)
+                }
+                
+                let solution = Solution(
+                    summary: "Remove extraneous \(extraOptionsDirective.scope) \(Options.directiveName.singleQuoted) directive",
+                    replacements: [
+                        Replacement(range: range, replacement: "")
+                    ]
+                )
+                
+                return Problem(diagnostic: diagnostic, possibleSolutions: [solution])
+            }
+            
+            diagnosticEngine.emit(extraGlobalOptionsProblems)
+        } else {
+            options = globalOptions.first
+        }
+        
         if LinkResolutionMigrationConfiguration.shouldSetUpHierarchyBasedLinkResolver {
             hierarchyBasedLinkResolver = hierarchyBasedResolver
             hierarchyBasedResolver.addMappingForRoots(bundle: bundle)

Sources/SwiftDocC/Infrastructure/Symbol Graph/GeneratedDocumentationTopics.swift

@@ -185,7 +185,7 @@ enum GeneratedDocumentationTopics {
             availableSourceLanguages: automaticCurationSourceLanguages,
             name: DocumentationNode.Name.conceptual(title: title),
             markup: Document(parsing: ""),
-            semantic: Article(markup: nil, metadata: nil, redirects: nil)
+            semantic: Article(markup: nil, metadata: nil, redirects: nil, options: [:])
         )
 
         let collectionTaskGroups = try AutomaticCuration.topics(for: temporaryCollectionNode, withTrait: nil, context: context)

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

@@ -123,6 +123,14 @@ public struct AutomaticCuration {
         renderContext: RenderContext?,
         renderer: DocumentationContentRenderer
     ) throws -> TaskGroup? {
+        if let automaticSeeAlsoOption = node.options?.automaticSeeAlsoBehavior
+            ?? context.options?.automaticSeeAlsoBehavior
+        {
+            guard automaticSeeAlsoOption == .siblingPages else {
+                return nil
+            }
+        }
+        
         // First try getting the canonical path from a render context, default to the documentation context
         guard let canonicalPath = renderContext?.store.content(for: node.reference)?.canonicalPath ?? context.pathsTo(node.reference).first,
             !canonicalPath.isEmpty else {

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

@@ -61,6 +61,11 @@ public struct DocumentationNode {
 
     /// If true, the node was created implicitly and should not generally be rendered as a page of documentation.
     public var isVirtual: Bool
+    
+    /// The authored options for this node.
+    ///
+    /// Allows for control of settings such as automatic see also generation.
+    public var options: Options?
 
     /// A discrete unit of documentation
     struct DocumentationChunk {
@@ -137,6 +142,13 @@ public struct DocumentationNode {
         self.platformNames = platformNames
         self.docChunks = [DocumentationChunk(source: .sourceCode(location: nil), markup: markup)]
         self.isVirtual = isVirtual
+        
+        if let article = semantic as? Article {
+            self.options = article.options[.local]
+        } else {
+            self.options = nil
+        }
+        
         updateAnchorSections()
     }
 
@@ -351,6 +363,8 @@ public struct DocumentationNode {
             )
         }
 
+        options = documentationExtension?.options[.local]
+        
         updateAnchorSections()
     }
 
@@ -603,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,9 @@ 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.
     public var topicSections: [TaskGroupRenderSection] {
         get { getVariantDefaultValue(keyPath: \.topicSectionsVariants) }
@@ -234,6 +237,7 @@ public struct RenderNode: VariantContainer {
     public init(identifier: ResolvedTopicReference, kind: Kind) {
         self.identifier = identifier
         self.kind = kind
+        self.topicSectionsStyle = .list
     }
 
     // MARK: Tutorials nodes

Sources/SwiftDocC/Model/Rendering/RenderNode/RenderNode+Codable.swift

@@ -13,7 +13,7 @@ import Foundation
 extension RenderNode: Codable {
     private enum CodingKeys: CodingKey {
         case schemaVersion, identifier, sections, references, metadata, kind, hierarchy
-        case abstract, topicSections, defaultImplementationsSections, primaryContentSections, relationshipsSections, declarationSections, seeAlsoSections, returnsSection, parametersSection, sampleCodeDownload, downloadNotAvailableSummary, deprecationSummary, diffAvailability, interfaceLanguage, variants, variantOverrides
+        case abstract, topicSections, topicSectionsStyle, defaultImplementationsSections, primaryContentSections, relationshipsSections, declarationSections, seeAlsoSections, returnsSection, parametersSection, sampleCodeDownload, downloadNotAvailableSummary, deprecationSummary, diffAvailability, interfaceLanguage, variants, variantOverrides
     }
 
     public init(from decoder: Decoder) throws {
@@ -26,6 +26,7 @@ extension RenderNode: Codable {
         metadata = try container.decode(RenderMetadata.self, forKey: .metadata)
         kind = try container.decode(Kind.self, forKey: .kind)
         hierarchy = try container.decodeIfPresent(RenderHierarchy.self, forKey: .hierarchy)
+        topicSectionsStyle = try container.decodeIfPresent(TopicsSectionStyle.self, forKey: .topicSectionsStyle) ?? .list
 
         primaryContentSectionsVariants = try container.decodeVariantCollectionArrayIfPresent(
             ofValueType: CodableContentSection?.self,
@@ -79,6 +80,9 @@ extension RenderNode: Codable {
         try container.encode(metadata, forKey: .metadata)
         try container.encode(kind, forKey: .kind)
         try container.encode(hierarchy, forKey: .hierarchy)
+        if topicSectionsStyle != .list {
+            try container.encode(topicSectionsStyle, forKey: .topicSectionsStyle)
+        }
 
         try container.encodeVariantCollection(abstractVariants, forKey: .abstract, encoder: encoder)
 

Sources/SwiftDocC/Model/Rendering/RenderNodeTranslator.swift

@@ -703,12 +703,15 @@ public struct RenderNodeTranslator: SemanticVisitor {
             return sections
         } ?? .init(defaultValue: [])
 
-
-        if node.topicSections.isEmpty {
-            // Set an eyebrow for articles
-            node.metadata.roleHeading = "Article"
+        node.topicSectionsStyle = topicsSectionStyle(for: documentationNode)
+        
+        if shouldCreateAutomaticRoleHeading(for: documentationNode) {
+            if node.topicSections.isEmpty {
+                // Set an eyebrow for articles
+                node.metadata.roleHeading = "Article"
+            }
+            node.metadata.role = contentRenderer.roleForArticle(article, nodeKind: documentationNode.kind).rawValue
         }
-        node.metadata.role = contentRenderer.roleForArticle(article, nodeKind: documentationNode.kind).rawValue
 
         node.seeAlsoSectionsVariants = VariantCollection<[TaskGroupRenderSection]>(
             from: documentationNode.availableVariantTraits,
@@ -1038,6 +1041,39 @@ public struct RenderNodeTranslator: SemanticVisitor {
         return reference
     }
 
+    private func shouldCreateAutomaticRoleHeading(for node: DocumentationNode) -> Bool {
+        var shouldCreateAutomaticRoleHeading = true
+        if let automaticTitleHeadingOption = node.options?.automaticTitleHeadingBehavior
+            ?? context.options?.automaticTitleHeadingBehavior
+        {
+            shouldCreateAutomaticRoleHeading = automaticTitleHeadingOption == .pageKind
+        }
+        
+        return shouldCreateAutomaticRoleHeading
+    }
+    
+    private func topicsSectionStyle(for node: DocumentationNode) -> RenderNode.TopicsSectionStyle {
+        let topicsVisualStyleOption: TopicsVisualStyle.Style
+        if let topicsSectionStyleOption = node.options?.topicsVisualStyle
+            ?? context.options?.topicsVisualStyle
+        {
+            topicsVisualStyleOption = topicsSectionStyleOption
+        } else {
+            topicsVisualStyleOption = .list
+        }
+        
+        switch topicsVisualStyleOption {
+        case .list:
+            return .list
+        case .compactGrid:
+            return .compactGrid
+        case .detailedGrid:
+            return .detailedGrid
+        case .hidden:
+            return .hidden
+        }
+    }
+    
     public mutating func visitSymbol(_ symbol: Symbol) -> RenderTree? {
         let documentationNode = try! context.entity(with: identifier)
 
@@ -1095,10 +1131,13 @@ public struct RenderNodeTranslator: SemanticVisitor {
 
         node.metadata.requiredVariants = VariantCollection<Bool>(from: symbol.isRequiredVariants) ?? .init(defaultValue: false)
         node.metadata.role = contentRenderer.role(for: documentationNode.kind).rawValue
-        node.metadata.roleHeadingVariants = VariantCollection<String?>(from: symbol.roleHeadingVariants)
         node.metadata.titleVariants = VariantCollection<String?>(from: symbol.titleVariants)
         node.metadata.externalIDVariants = VariantCollection<String?>(from: symbol.externalIDVariants)
 
+        if shouldCreateAutomaticRoleHeading(for: documentationNode) {
+            node.metadata.roleHeadingVariants = VariantCollection<String?>(from: symbol.roleHeadingVariants)
+        }
+        
         node.metadata.symbolKindVariants = VariantCollection<String?>(from: symbol.kindVariants) { _, kindVariants in
             kindVariants.identifier.renderingIdentifier
         } ?? .init(defaultValue: nil)
@@ -1308,6 +1347,8 @@ public struct RenderNodeTranslator: SemanticVisitor {
             return sections
         } ?? .init(defaultValue: [])
 
+        node.topicSectionsStyle = topicsSectionStyle(for: documentationNode)
+        
         node.defaultImplementationsSectionsVariants = VariantCollection<[TaskGroupRenderSection]>(
             from: symbol.defaultImplementationsVariants,
             symbol.relationshipsVariants

Sources/SwiftDocC/Model/Rendering/TopicsSectionStyle.swift

@@ -0,0 +1,30 @@
+/*
+ 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
+*/
+
+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/Article/Article.swift

@@ -21,6 +21,8 @@ public final class Article: Semantic, MarkupConvertible, Abstracted, Redirected,
     let markup: Markup?
     /// An optional container for metadata that's unrelated to the article's content.
     private(set) var metadata: Metadata?
+    /// An optional container for options that are unrelated to the article's content.
+    private(set) var options: [Options.Scope : Options]
     /// An optional list of previously known locations for this article.
     private(set) public var redirects: [Redirect]?
 
@@ -30,10 +32,11 @@ public final class Article: Semantic, MarkupConvertible, Abstracted, Redirected,
     ///   - markup: The markup that makes up this article's content.
     ///   - metadata: An optional container for metadata that's unrelated to the article's content.
     ///   - redirects: An optional list of previously known locations for this article.
-    init(markup: Markup?, metadata: Metadata?, redirects: [Redirect]?) {
+    init(markup: Markup?, metadata: Metadata?, redirects: [Redirect]?, options: [Options.Scope : Options]) {
         let markupModel = markup.map { DocumentationMarkup(markup: $0) }
 
         self.markup = markup
+        self.options = options
         self.metadata = metadata
         self.redirects = redirects
         self.discussion = markupModel?.discussionSection
@@ -46,7 +49,7 @@ public final class Article: Semantic, MarkupConvertible, Abstracted, Redirected,
     }
 
     convenience init(title: Heading?, abstractSection: AbstractSection?, discussion: DiscussionSection?, topics: TopicsSection?, seeAlso: SeeAlsoSection?, deprecationSummary: MarkupContainer?, metadata: Metadata?, redirects: [Redirect]?, automaticTaskGroups: [AutomaticTaskGroupSection]? = nil) {
-        self.init(markup: nil, metadata: metadata, redirects: redirects)
+        self.init(markup: nil, metadata: metadata, redirects: redirects, options: [:])
         self.title = title
         self.abstractSection = abstractSection
         self.discussion = discussion
@@ -139,7 +142,61 @@ public final class Article: Semantic, MarkupConvertible, Abstracted, Redirected,
         }
 
         var optionalMetadata = metadata.first
+        
+        let options: [Options]
+        (options, remainder) = remainder.categorize { child -> Options? in
+            guard let childDirective = child as? BlockDirective, childDirective.name == Options.directiveName else {
+                return nil
+            }
+            return Options(
+                from: childDirective,
+                source: source,
+                for: bundle,
+                in: context,
+                problems: &problems
+            )
+        }
+        
+        let allCategorizedOptions = Dictionary(grouping: options, by: \.scope)
+        
+        for (scope, options) in allCategorizedOptions {
+            let extraOptions = options.dropFirst()
+            guard !extraOptions.isEmpty else {
+                continue
+            }
+            
+            let extraOptionsProblems = extraOptions.map { extraOptionsDirective -> Problem in
+                let diagnostic = Diagnostic(
+                    source: source,
+                    severity: .warning,
+                    range: extraOptionsDirective.originalMarkup.range,
+                    identifier: "org.swift.docc.HasAtMostOne<\(Article.self), \(Options.self), \(scope)>.DuplicateChildren",
+                    summary: "Duplicate \(scope) \(Options.directiveName.singleQuoted) directive",
+                    explanation: """
+                    An article can only contain a single \(Options.directiveName.singleQuoted) \
+                    directive with the \(scope.rawValue.singleQuoted) scope.
+                    """
+                )
 
+                guard let range = extraOptionsDirective.originalMarkup.range else {
+                    return Problem(diagnostic: diagnostic)
+                }
+                
+                let solution = Solution(
+                    summary: "Remove extraneous \(scope) \(Options.directiveName.singleQuoted) directive",
+                    replacements: [
+                        Replacement(range: range, replacement: "")
+                    ]
+                )
+                
+                return Problem(diagnostic: diagnostic, possibleSolutions: [solution])
+            }
+            
+            problems.append(contentsOf: extraOptionsProblems)
+        }
+        
+        let relevantCategorizedOptions = allCategorizedOptions.compactMapValues(\.first)
+        
         let isDocumentationExtension = title.child(at: 0) is AnyLink
         if !isDocumentationExtension, let metadata = optionalMetadata, let displayName = metadata.displayName {
             let diagnosticSummary = """
@@ -164,7 +221,12 @@ public final class Article: Semantic, MarkupConvertible, Abstracted, Redirected,
             optionalMetadata = Metadata(originalMarkup: metadata.originalMarkup, documentationExtension: metadata.documentationOptions, technologyRoot: metadata.technologyRoot, displayName: nil)
         }
 
-        self.init(markup: markup, metadata: optionalMetadata, redirects: redirects.isEmpty ? nil : redirects)
+        self.init(
+            markup: markup,
+            metadata: optionalMetadata,
+            redirects: redirects.isEmpty ? nil : redirects,
+            options: relevantCategorizedOptions
+        )
     }
 
     /// Visit the article using a semantic visitor and return the result of visiting the article.