Add authoring support for @AutomaticArticleSubheading directive (#425)

Adds a new `@AutomaticArticleSubheading` directive that allows for
customizing the way an article page’s subheading is autogenerated.

`@AutomaticArticleSubheading` gives authors control over the automatic
"Overview" subheading that is automatically created above the first
paragraph in any articles that don't include an explicitly authored H2
heading.

By setting `@AutomaticArticleSubheading` to `disabled` an author can
choose to start an article more directly with a paragraph of text or an
image instead of always beginning with a subheading.

Example:

    # What's New in SlothCreator

    @options {
        @AutomaticArticleSubheading(disabled)
    }

    ![A sloth on a tree wearing a fedora.](sloth-fedora)

    Let's check out what's new in SlothCreator!

    ...

Details:

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

   - `enabled`: A subheading will be auto-generated for the page,
     following Swift-DocC’s current default behavior.

     Today, this means that (in the absence of some other H2 heading
     below the summary sentence) an “Overview” subheading will be
     created for the article. The specifics of this behavior could
     change in the future; using `enabled` is just a way to opt-in to
     Swift-DocC’s default and allows for setting a global setting of
     `disabled` while still enabling the feature on certain pages.

   - `disabled`: A subheading will not be auto-generated for the page.
     To include a subheading, the author can explicitly write one.

This change is described on the Swift forums here:
https://forums.swift.org/t/customizing-the-auto-generated-overview-heading-in-swift-docc-articles/61390

Resolves rdar://101368956

Author: ethan-kusters

Sources/SwiftDocC/Model/Rendering/RenderNodeTranslator.swift

@@ -630,8 +630,9 @@ public struct RenderNodeTranslator: SemanticVisitor {
             var title: String?
             if let first = discussionContent.first, case RenderBlockContent.heading = first {
                 title = nil
-            } else {
-                // For articles hardcode an overview title
+            } else if shouldCreateAutomaticArticleSubheading(for: documentationNode) {
+                // For articles hardcode an overview title unless the user explicitly
+                // opts-out with the `@AutomaticArticleSubheading` directive.
                 title = "Overview"
             }
             node.primaryContentSections.append(ContentRenderSection(kind: .content, content: discussionContent, heading: title))
@@ -1077,6 +1078,19 @@ public struct RenderNodeTranslator: SemanticVisitor {
         return shouldCreateAutomaticRoleHeading
     }
 
+    private func shouldCreateAutomaticArticleSubheading(for node: DocumentationNode) -> Bool {
+        let shouldCreateAutomaticArticleSubheading: Bool
+        if let automaticSubheadingOption = node.options?.automaticArticleSubheadingBehavior
+            ?? context.options?.automaticArticleSubheadingBehavior
+        {
+            shouldCreateAutomaticArticleSubheading = !(automaticSubheadingOption == .disabled)
+        } else {
+            shouldCreateAutomaticArticleSubheading = true
+        }
+        
+        return shouldCreateAutomaticArticleSubheading
+    }
+    
     private func topicsSectionStyle(for node: DocumentationNode) -> RenderNode.TopicsSectionStyle {
         let topicsVisualStyleOption: TopicsVisualStyle.Style
         if let topicsSectionStyleOption = node.options?.topicsVisualStyle

Sources/SwiftDocC/Semantics/Options/AutomaticArticleSubheading.swift

@@ -0,0 +1,44 @@
+/*
+ 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 that modifies Swift-DocC's default behavior for automatic subheading generation on
+/// article pages.
+///
+/// By default, articles receive a second-level "Overview" heading unless the author explicitly writes
+/// some other H2 heading below the abstract. This allows for opting out of that behavior.
+public class AutomaticArticleSubheading: Semantic, AutomaticDirectiveConvertible {
+    public let originalMarkup: BlockDirective
+    
+    /// The specified behavior for automatic subheading generation.
+    @DirectiveArgumentWrapped(name: .unnamed)
+    public private(set) var behavior: Behavior
+    
+    /// A behavior for automatic subheading generation.
+    public enum Behavior: String, CaseIterable, DirectiveArgumentValueConvertible {
+        /// No subheading should be created for the article.
+        case disabled
+        
+        /// An overview subheading should be created containing the article's
+        /// first paragraph of content.
+        case enabled
+    }
+    
+    static var keyPaths: [String : AnyKeyPath] = [
+        "behavior"  : \AutomaticArticleSubheading._behavior,
+    ]
+    
+    @available(*, deprecated, message: "Do not call directly. Required for 'AutomaticDirectiveConvertible'.")
+    required init(originalMarkup: BlockDirective) {
+        self.originalMarkup = originalMarkup
+    }
+}

Sources/SwiftDocC/Semantics/Options/Options.swift

@@ -26,6 +26,9 @@ public class Options: Semantic, AutomaticDirectiveConvertible {
     @ChildDirective
     public private(set) var _automaticTitleHeading: AutomaticTitleHeading? = nil
 
+    @ChildDirective
+    public private(set) var _automaticArticleSubheading: AutomaticArticleSubheading? = nil
+    
     @ChildDirective
     public private(set) var _topicsVisualStyle: TopicsVisualStyle? = nil
 
@@ -39,6 +42,11 @@ public class Options: Semantic, AutomaticDirectiveConvertible {
         return _automaticTitleHeading?.behavior
     }
 
+    /// If given, the authored behavior for automatic article subheading generation.
+    public var automaticArticleSubheadingBehavior: AutomaticArticleSubheading.Behavior? {
+        return _automaticArticleSubheading?.behavior
+    }
+    
     /// If given, the authored style for a page's Topics section.
     public var topicsVisualStyle: TopicsVisualStyle.Style? {
         return _topicsVisualStyle?.style
@@ -58,6 +66,7 @@ public class Options: Semantic, AutomaticDirectiveConvertible {
         "_automaticSeeAlso"      : \Options.__automaticSeeAlso,
         "_automaticTitleHeading" : \Options.__automaticTitleHeading,
         "_topicsVisualStyle"     : \Options.__topicsVisualStyle,
+        "_automaticArticleSubheading"   : \Options.__automaticArticleSubheading,
     ]
 
     @available(*, deprecated, message: "Do not call directly. Required for 'AutomaticDirectiveConvertible'.")

Tests/SwiftDocCTests/Model/SemaToRenderNodeTests.swift

@@ -1860,12 +1860,9 @@ Document
             """
         )
     }
-
-    /*
-        Asserts if `expectedRoleHeading` does not match the the parsed render node's `roleHeading` after it's parsed.
-        Uses 'TestBundle's documentation as a base for compiling, overwriting 'article2' with `content`.
-    */
-    private func assertRoleHeadingForArticleInTestBundle(expectedRoleHeading: String?, content: String, file: StaticString = #file, line: UInt = #line) throws {
+    
+    
+    private func renderNodeForArticleInTestBundle(content: String) throws -> RenderNode {
         // Overwrite the article so we can test the article eyebrow for articles without task groups
         let sourceURL = Bundle.module.url(
             forResource: "TestBundle", withExtension: "docc", subdirectory: "Test Bundles")!
@@ -1879,10 +1876,71 @@ Document
         let node = try context.entity(with: ResolvedTopicReference(bundleIdentifier: bundle.identifier, path: "/documentation/Test-Bundle/article2", sourceLanguage: .swift))
         let article = node.semantic as! Article
         var translator = RenderNodeTranslator(context: context, bundle: bundle, identifier: node.reference, source: nil)
-        let renderNode = translator.visit(article) as! RenderNode
-
+        return translator.visit(article) as! RenderNode
+    }
+    
+    /*
+        Asserts if `expectedRoleHeading` does not match the the parsed render node's `roleHeading` after it's parsed.
+        Uses 'TestBundle's documentation as a base for compiling, overwriting 'article2' with `content`.
+    */
+    private func assertRoleHeadingForArticleInTestBundle(expectedRoleHeading: String?, content: String, file: StaticString = #file, line: UInt = #line) throws {
+        let renderNode = try renderNodeForArticleInTestBundle(content: content)
         XCTAssertEqual(expectedRoleHeading, renderNode.metadata.roleHeading, file: (file), line: line)
     }
+    
+    
+    func testDisablingAutomaticArticleSubheadingGeneration() throws {
+        // Assert that by default, articles include an "Overview" heading even if it's not authored.
+        do {
+            let articleRenderNode = try renderNodeForArticleInTestBundle(
+                content: """
+                # Article 2
+                
+                This is article 2.
+                
+                This is the article's second paragraph.
+                """
+            )
+            
+            let firstContentSection = try XCTUnwrap(
+                articleRenderNode.primaryContentSections.first as? ContentRenderSection
+            )
+            if case let .heading(heading) = firstContentSection.content.first {
+                XCTAssertEqual(heading.text, "Overview")
+            } else {
+                XCTFail("By default an article should receive an autogenerated 'Overview' heading.")
+            }
+            
+            XCTAssertEqual(firstContentSection.content.count, 2)
+        }
+        
+        // Assert that disabling the automatic behavior with the option directive works as expected.
+        do {
+            let articleRenderNode = try renderNodeForArticleInTestBundle(
+                content: """
+                # Article 2
+                
+                @Options {
+                    @AutomaticArticleSubheading(disabled)
+                }
+                
+                This is article 2.
+                
+                This is the second paragraph of the article.
+                """
+            )
+            
+            let firstContentSection = try XCTUnwrap(
+                articleRenderNode.primaryContentSections.first as? ContentRenderSection
+            )
+            if case let .paragraph(paragraph) = firstContentSection.content.first {
+                XCTAssertEqual(paragraph.inlineContent.first?.plainText, "This is the second paragraph of the article.")
+            } else {
+                XCTFail("An article with the '@AutomaticArticleSubheading(disabled)' specified should not receive an autogenerated heading.")
+            }
+            XCTAssertEqual(firstContentSection.content.count, 1)
+        }
+    }
 
     /// Verifies we emit the correct warning for external links in topic task groups.
     func testWarnForExternalLinksInTopicTaskGroups() throws {

Tests/SwiftDocCTests/Semantics/DirectiveInfrastructure/DirectiveIndexTests.swift

@@ -18,6 +18,7 @@ class DirectiveIndexTests: XCTestCase {
             DirectiveIndex.shared.indexedDirectives.keys.sorted(),
             [
                 "Assessments",
+                "AutomaticArticleSubheading",
                 "AutomaticSeeAlso",
                 "AutomaticTitleHeading",
                 "Chapter",

Tests/SwiftDocCTests/Semantics/Options/OptionsTests.swift

@@ -259,6 +259,7 @@ class OptionsTests: XCTestCase {
                 @AutomaticTitleHeading(pageKind)
                 @AutomaticSeeAlso(disabled)
                 @TopicsVisualStyle(detailedGrid)
+                @AutomaticArticleSubheading(enabled)
             }
             """
         }
@@ -267,6 +268,7 @@ class OptionsTests: XCTestCase {
         XCTAssertEqual(options?.automaticTitleHeadingBehavior, .pageKind)
         XCTAssertEqual(options?.automaticSeeAlsoBehavior, .disabled)
         XCTAssertEqual(options?.topicsVisualStyle, .detailedGrid)
+        XCTAssertEqual(options?.automaticArticleSubheadingBehavior, .enabled)
     }
 
     func testUnsupportedChild() throws {
@@ -292,4 +294,61 @@ class OptionsTests: XCTestCase {
             ]
         )
     }
+    
+    func testAutomaticArticleSubheading() throws {
+        do {
+            let (problems, options) = try parseDirective(Options.self) {
+                """
+                @Options {
+                }
+                """
+            }
+            
+            XCTAssertTrue(problems.isEmpty)
+            let unwrappedOptions = try XCTUnwrap(options)
+            XCTAssertNil(unwrappedOptions.automaticArticleSubheadingBehavior)
+        }
+        
+        do {
+            let (problems, options) = try parseDirective(Options.self) {
+                """
+                @Options {
+                    @AutomaticArticleSubheading(randomArgument)
+                }
+                """
+            }
+            
+            XCTAssertEqual(problems, ["2: warning – org.swift.docc.HasArgument.unlabeled.ConversionFailed"])
+            let unwrappedOptions = try XCTUnwrap(options)
+            XCTAssertNil(unwrappedOptions.automaticArticleSubheadingBehavior)
+        }
+        
+        do {
+            let (problems, options) = try parseDirective(Options.self) {
+                """
+                @Options {
+                    @AutomaticArticleSubheading(disabled)
+                }
+                """
+            }
+            
+            XCTAssertTrue(problems.isEmpty)
+            let unwrappedOptions = try XCTUnwrap(options)
+            XCTAssertEqual(unwrappedOptions.automaticArticleSubheadingBehavior, .disabled)
+        }
+        
+        do {
+            let (problems, options) = try parseDirective(Options.self) {
+                """
+                @Options {
+                    @AutomaticArticleSubheading(enabled)
+                }
+                """
+            }
+            
+            XCTAssertTrue(problems.isEmpty)
+            let unwrappedOptions = try XCTUnwrap(options)
+            XCTAssertEqual(unwrappedOptions.automaticArticleSubheadingBehavior, .enabled)
+        }
+    }
 }