From 3926574e7e3bc72882ab26598c731dc84296894b Mon Sep 17 00:00:00 2001 From: Emily Chen Date: Tue, 6 Jun 2023 10:58:20 -0700 Subject: [PATCH 01/16] added support for title heading directive --- .../OutOfProcessReferenceResolver.swift | 2 +- .../Rendering/RenderNode/RenderMetadata.swift | 7 ++++ .../Rendering/RenderNodeTranslator.swift | 5 +++ .../SwiftDocC/Semantics/Article/Article.swift | 2 +- .../Semantics/Metadata/Metadata.swift | 15 +++++-- .../Semantics/Metadata/TitleHeading.swift | 39 +++++++++++++++++++ .../API Reference Syntax/Metadata.md | 11 ++++++ 7 files changed, 75 insertions(+), 6 deletions(-) create mode 100644 Sources/SwiftDocC/Semantics/Metadata/TitleHeading.swift diff --git a/Sources/SwiftDocC/Infrastructure/External Data/OutOfProcessReferenceResolver.swift b/Sources/SwiftDocC/Infrastructure/External Data/OutOfProcessReferenceResolver.swift index 27d174619f..29dd66537c 100644 --- a/Sources/SwiftDocC/Infrastructure/External Data/OutOfProcessReferenceResolver.swift +++ b/Sources/SwiftDocC/Infrastructure/External Data/OutOfProcessReferenceResolver.swift @@ -276,7 +276,7 @@ public class OutOfProcessReferenceResolver: ExternalReferenceResolver, FallbackR // with a render node. if let topicImages = resolvedInformation.topicImages, !topicImages.isEmpty { - let metadata = node.metadata ?? Metadata(originalMarkup: BlockDirective(name: "Metadata", children: []), documentationExtension: nil, technologyRoot: nil, displayName: nil) + let metadata = node.metadata ?? Metadata(originalMarkup: BlockDirective(name: "Metadata", children: []), documentationExtension: nil, technologyRoot: nil, displayName: nil, titleHeading: nil) metadata.pageImages = topicImages.map { topicImage in let purpose: PageImage.Purpose diff --git a/Sources/SwiftDocC/Model/Rendering/RenderNode/RenderMetadata.swift b/Sources/SwiftDocC/Model/Rendering/RenderNode/RenderMetadata.swift index fd78269137..beabbd86ff 100644 --- a/Sources/SwiftDocC/Model/Rendering/RenderNode/RenderMetadata.swift +++ b/Sources/SwiftDocC/Model/Rendering/RenderNode/RenderMetadata.swift @@ -85,6 +85,10 @@ public struct RenderMetadata: VariantContainer { /// Author provided custom metadata describing the page. public var customMetadata: [String: String] = [:] + + /// ----------------------------------------------------------------------------- + /// TODO: MODIFY THIS SECTION????? WHATS THE DIFFERENCE BETWEEN A TITLE AND A TITLE HEADING??? + /// The title of the page. public var title: String? { get { getVariantDefaultValue(keyPath: \.titleVariants) } @@ -93,7 +97,10 @@ public struct RenderMetadata: VariantContainer { /// The variants of the title. public var titleVariants: VariantCollection = .init(defaultValue: nil) + + /// END OF TODO SECTION ----------------------------------------------------------------------------- + /// An identifier for a symbol generated externally. public var externalID: String? { get { getVariantDefaultValue(keyPath: \.externalIDVariants) } diff --git a/Sources/SwiftDocC/Model/Rendering/RenderNodeTranslator.swift b/Sources/SwiftDocC/Model/Rendering/RenderNodeTranslator.swift index b3812146b9..ffbada61f9 100644 --- a/Sources/SwiftDocC/Model/Rendering/RenderNodeTranslator.swift +++ b/Sources/SwiftDocC/Model/Rendering/RenderNodeTranslator.swift @@ -847,6 +847,11 @@ public struct RenderNodeTranslator: SemanticVisitor { node.metadata.roleHeading = pageKind.kind.titleHeading } + if let titleHeading = article.metadata?.titleHeading { + node.metadata.role = titleHeading.headingText + node.metadata.roleHeading = titleHeading.headingText + } + collectedTopicReferences.append(contentsOf: contentCompiler.collectedTopicReferences) node.references = createTopicRenderReferences() diff --git a/Sources/SwiftDocC/Semantics/Article/Article.swift b/Sources/SwiftDocC/Semantics/Article/Article.swift index ad02f14ea1..afdca0f3cb 100644 --- a/Sources/SwiftDocC/Semantics/Article/Article.swift +++ b/Sources/SwiftDocC/Semantics/Article/Article.swift @@ -218,7 +218,7 @@ public final class Article: Semantic, MarkupConvertible, Abstracted, Redirected, problems.append(Problem(diagnostic: diagnostic, possibleSolutions: solutions)) // Remove the display name customization from the article's metadata. - optionalMetadata = Metadata(originalMarkup: metadata.originalMarkup, documentationExtension: metadata.documentationOptions, technologyRoot: metadata.technologyRoot, displayName: nil) + optionalMetadata = Metadata(originalMarkup: metadata.originalMarkup, documentationExtension: metadata.documentationOptions, technologyRoot: metadata.technologyRoot, displayName: nil, titleHeading: metadata.titleHeading) } self.init( diff --git a/Sources/SwiftDocC/Semantics/Metadata/Metadata.swift b/Sources/SwiftDocC/Semantics/Metadata/Metadata.swift index 9f75fee71c..57d7cd3a92 100644 --- a/Sources/SwiftDocC/Semantics/Metadata/Metadata.swift +++ b/Sources/SwiftDocC/Semantics/Metadata/Metadata.swift @@ -27,6 +27,7 @@ import Markdown /// - ``Availability`` /// - ``PageKind`` /// - ``SupportedLanguage`` +/// - ``TitleHeading`` public final class Metadata: Semantic, AutomaticDirectiveConvertible { public let originalMarkup: BlockDirective @@ -68,6 +69,9 @@ public final class Metadata: Semantic, AutomaticDirectiveConvertible { var pageColor: PageColor.Color? { _pageColor?.color } + + @ChildDirective + var titleHeading: TitleHeading? = nil static var keyPaths: [String : AnyKeyPath] = [ "documentationOptions" : \Metadata._documentationOptions, @@ -79,7 +83,8 @@ public final class Metadata: Semantic, AutomaticDirectiveConvertible { "availability" : \Metadata._availability, "pageKind" : \Metadata._pageKind, "supportedLanguages" : \Metadata._supportedLanguages, - "_pageColor" : \Metadata.__pageColor, + "_pageColor" : \Metadata.__pageColor, + "titleHeading" : \Metadata._titleHeading, ] /// Creates a metadata object with a given markup, documentation extension, and technology root. @@ -87,12 +92,14 @@ public final class Metadata: Semantic, AutomaticDirectiveConvertible { /// - originalMarkup: The original markup for this metadata directive. /// - documentationExtension: Optional configuration that describes how this documentation extension file merges or overrides the in-source documentation. /// - technologyRoot: Optional configuration to make this page root-level documentation. - /// - displayName:Optional configuration to customize this page's symbol's display name. - init(originalMarkup: BlockDirective, documentationExtension: DocumentationExtension?, technologyRoot: TechnologyRoot?, displayName: DisplayName?) { + /// - displayName: Optional configuration to customize this page's symbol's display name. + /// - titleHeading: Optional configuration to customize the text of this page's title heading. + init(originalMarkup: BlockDirective, documentationExtension: DocumentationExtension?, technologyRoot: TechnologyRoot?, displayName: DisplayName?, titleHeading: TitleHeading?) { self.originalMarkup = originalMarkup self.documentationOptions = documentationExtension self.technologyRoot = technologyRoot self.displayName = displayName + self.titleHeading = titleHeading } @available(*, deprecated, message: "Do not call directly. Required for 'AutomaticDirectiveConvertible'.") @@ -102,7 +109,7 @@ public final class Metadata: Semantic, AutomaticDirectiveConvertible { func validate(source: URL?, for bundle: DocumentationBundle, in context: DocumentationContext, problems: inout [Problem]) -> Bool { // Check that something is configured in the metadata block - if documentationOptions == nil && technologyRoot == nil && displayName == nil && pageImages.isEmpty && customMetadata.isEmpty && callToAction == nil && availability.isEmpty && pageKind == nil && pageColor == nil { + if documentationOptions == nil && technologyRoot == nil && displayName == nil && pageImages.isEmpty && customMetadata.isEmpty && callToAction == nil && availability.isEmpty && pageKind == nil && pageColor == nil && titleHeading == nil { let diagnostic = Diagnostic( source: source, severity: .information, diff --git a/Sources/SwiftDocC/Semantics/Metadata/TitleHeading.swift b/Sources/SwiftDocC/Semantics/Metadata/TitleHeading.swift new file mode 100644 index 0000000000..9762b4cfe1 --- /dev/null +++ b/Sources/SwiftDocC/Semantics/Metadata/TitleHeading.swift @@ -0,0 +1,39 @@ +/* + This source file is part of the Swift.org open source project + + Copyright (c) 2023 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 customizing the text of a page-title heading (aka an eyebrow or kick). +/// +/// @TitleHeading accepts an unnamed parameter containing containing the page-title’s heading text. +/// +/// This directive is only valid within a top-level ``Metadata`` directive: +/// ```markdown +/// @Metadata { +/// @TitleHeading("Release Notes") +/// } +/// ``` +public final class TitleHeading: Semantic, AutomaticDirectiveConvertible { + public let originalMarkup: BlockDirective + + /// An unnamed parameter containing containing the page-title’s heading text. + @DirectiveArgumentWrapped(name: .unnamed) + public var headingText: String + + static var keyPaths: [String : AnyKeyPath] = [ + "headingText" : \TitleHeading._headingText, + ] + + @available(*, deprecated, message: "Do not call directly. Required for 'AutomaticDirectiveConvertible'.") + init(originalMarkup: BlockDirective) { + self.originalMarkup = originalMarkup + } +} \ No newline at end of file diff --git a/Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/Metadata.md b/Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/Metadata.md index 9f7c6209fe..b0cc478f59 100644 --- a/Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/Metadata.md +++ b/Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/Metadata.md @@ -30,6 +30,16 @@ Use the `Metadata` directive with the ``DisplayName`` directive to configure a s } ``` +Use the `Metadata` directive with the ``TitleHeading`` directive to configure the text of a page-title heading (also known as an eyebrow or kick). + +``` +# ``SlothCreator`` + +@Metadata { + @TitleHeading("Release Notes") +} +``` + ## Topics ### Extending or Overriding Source Documentation @@ -47,6 +57,7 @@ Use the `Metadata` directive with the ``DisplayName`` directive to configure a s - ``PageKind`` - ``PageColor`` - ``CallToAction`` +- ``TitleHeading`` ### Customizing the Languages of an Article From 04bbd9b4d6b0c114e6b3037acfd825f08da618b4 Mon Sep 17 00:00:00 2001 From: Emily Chen Date: Thu, 8 Jun 2023 20:19:44 -0700 Subject: [PATCH 02/16] implemented title heading directive --- .../SwiftDocC/Model/Rendering/RenderNodeTranslator.swift | 9 ++++++--- .../Infrastructure/TestExternalReferenceResolvers.swift | 2 +- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/Sources/SwiftDocC/Model/Rendering/RenderNodeTranslator.swift b/Sources/SwiftDocC/Model/Rendering/RenderNodeTranslator.swift index ffbada61f9..225e06f971 100644 --- a/Sources/SwiftDocC/Model/Rendering/RenderNodeTranslator.swift +++ b/Sources/SwiftDocC/Model/Rendering/RenderNodeTranslator.swift @@ -841,16 +841,15 @@ public struct RenderNodeTranslator: SemanticVisitor { node.metadata.platformsVariants = .init(defaultValue: renderAvailability) } } - + if let pageKind = article.metadata?.pageKind { node.metadata.role = pageKind.kind.renderRole.rawValue node.metadata.roleHeading = pageKind.kind.titleHeading } if let titleHeading = article.metadata?.titleHeading { - node.metadata.role = titleHeading.headingText node.metadata.roleHeading = titleHeading.headingText - } + } collectedTopicReferences.append(contentsOf: contentCompiler.collectedTopicReferences) node.references = createTopicRenderReferences() @@ -1252,6 +1251,10 @@ public struct RenderNodeTranslator: SemanticVisitor { if shouldCreateAutomaticRoleHeading(for: documentationNode) { node.metadata.roleHeadingVariants = VariantCollection(from: symbol.roleHeadingVariants) } + + if let titleHeading = documentationNode.metadata?.titleHeading { + node.metadata.roleHeadingVariants = VariantCollection(defaultValue: titleHeading.headingText) + } node.metadata.symbolKindVariants = VariantCollection(from: symbol.kindVariants) { _, kindVariants in kindVariants.identifier.renderingIdentifier diff --git a/Tests/SwiftDocCTests/Infrastructure/TestExternalReferenceResolvers.swift b/Tests/SwiftDocCTests/Infrastructure/TestExternalReferenceResolvers.swift index 6df8aa550d..23b7342446 100644 --- a/Tests/SwiftDocCTests/Infrastructure/TestExternalReferenceResolvers.swift +++ b/Tests/SwiftDocCTests/Infrastructure/TestExternalReferenceResolvers.swift @@ -159,7 +159,7 @@ class TestMultiResultExternalReferenceResolver: ExternalReferenceResolver, Fallb // This is a workaround for how external content is processed. See details in OutOfProcessReferenceResolver.addImagesAndCacheMediaReferences(to:from:) if let topicImages = entityInfo.topicImages { - let metadata = node.metadata ?? Metadata(originalMarkup: BlockDirective(name: "Metadata", children: []), documentationExtension: nil, technologyRoot: nil, displayName: nil) + let metadata = node.metadata ?? Metadata(originalMarkup: BlockDirective(name: "Metadata", children: []), documentationExtension: nil, technologyRoot: nil, displayName: nil, titleHeading: nil) metadata.pageImages = topicImages.map { topicImage, alt in let purpose: PageImage.Purpose From 96471e599beebf4a5db0d3a1dddfae378b5bc9b2 Mon Sep 17 00:00:00 2001 From: Emily Chen Date: Fri, 9 Jun 2023 11:45:25 -0700 Subject: [PATCH 03/16] add unit tests for title heading directive --- .../Rendering/RenderNode/RenderMetadata.swift | 7 -- .../Rendering/RenderNodeTranslatorTests.swift | 4 +- .../DirectiveIndexTests.swift | 1 + .../DirectiveMirrorTests.swift | 15 ++++- .../Semantics/MetadataTests.swift | 66 +++++++++++++++++++ 5 files changed, 83 insertions(+), 10 deletions(-) diff --git a/Sources/SwiftDocC/Model/Rendering/RenderNode/RenderMetadata.swift b/Sources/SwiftDocC/Model/Rendering/RenderNode/RenderMetadata.swift index beabbd86ff..e6eca99361 100644 --- a/Sources/SwiftDocC/Model/Rendering/RenderNode/RenderMetadata.swift +++ b/Sources/SwiftDocC/Model/Rendering/RenderNode/RenderMetadata.swift @@ -85,10 +85,6 @@ public struct RenderMetadata: VariantContainer { /// Author provided custom metadata describing the page. public var customMetadata: [String: String] = [:] - - /// ----------------------------------------------------------------------------- - /// TODO: MODIFY THIS SECTION????? WHATS THE DIFFERENCE BETWEEN A TITLE AND A TITLE HEADING??? - /// The title of the page. public var title: String? { get { getVariantDefaultValue(keyPath: \.titleVariants) } @@ -98,9 +94,6 @@ public struct RenderMetadata: VariantContainer { /// The variants of the title. public var titleVariants: VariantCollection = .init(defaultValue: nil) - /// END OF TODO SECTION ----------------------------------------------------------------------------- - - /// An identifier for a symbol generated externally. public var externalID: String? { get { getVariantDefaultValue(keyPath: \.externalIDVariants) } diff --git a/Tests/SwiftDocCTests/Rendering/RenderNodeTranslatorTests.swift b/Tests/SwiftDocCTests/Rendering/RenderNodeTranslatorTests.swift index 58148dc734..91f90b2296 100644 --- a/Tests/SwiftDocCTests/Rendering/RenderNodeTranslatorTests.swift +++ b/Tests/SwiftDocCTests/Rendering/RenderNodeTranslatorTests.swift @@ -230,7 +230,7 @@ class RenderNodeTranslatorTests: XCTestCase { let source = """ # My Article My introduction. - My exposè. + My exposé. My conclusion. """ let document = Document(parsing: source, options: .parseBlockDirectives) @@ -247,7 +247,7 @@ class RenderNodeTranslatorTests: XCTestCase { let source = """ # My Article My introduction. - My exposè. + My exposé. My conclusion. ## Topics ### Basics diff --git a/Tests/SwiftDocCTests/Semantics/DirectiveInfrastructure/DirectiveIndexTests.swift b/Tests/SwiftDocCTests/Semantics/DirectiveInfrastructure/DirectiveIndexTests.swift index 8af071f28f..01a1fa0592 100644 --- a/Tests/SwiftDocCTests/Semantics/DirectiveInfrastructure/DirectiveIndexTests.swift +++ b/Tests/SwiftDocCTests/Semantics/DirectiveInfrastructure/DirectiveIndexTests.swift @@ -48,6 +48,7 @@ class DirectiveIndexTests: XCTestCase { "Tab", "TabNavigator", "TechnologyRoot", + "TitleHeading", "TopicsVisualStyle", "Tutorial", "TutorialReference", diff --git a/Tests/SwiftDocCTests/Semantics/DirectiveInfrastructure/DirectiveMirrorTests.swift b/Tests/SwiftDocCTests/Semantics/DirectiveInfrastructure/DirectiveMirrorTests.swift index b2dd61a533..ab836b2a39 100644 --- a/Tests/SwiftDocCTests/Semantics/DirectiveInfrastructure/DirectiveMirrorTests.swift +++ b/Tests/SwiftDocCTests/Semantics/DirectiveInfrastructure/DirectiveMirrorTests.swift @@ -31,6 +31,19 @@ class DirectiveMirrorTests: XCTestCase { XCTAssertEqual(reflectedDirective.arguments["style"]?.propertyLabel, "style") XCTAssertEqual(reflectedDirective.arguments["style"]?.allowedValues, ["conceptual", "symbol"]) } + + func testReflectTitleHeadingDirective() { + let reflectedDirective = DirectiveMirror(reflecting: TitleHeading.self).reflectedDirective + + XCTAssertEqual(reflectedDirective.name, "TitleHeading") + XCTAssertFalse(reflectedDirective.allowsMarkup) + XCTAssertEqual(reflectedDirective.arguments.count, 1) + + XCTAssertEqual(reflectedDirective.arguments["headingText"]?.unnamed, true) + XCTAssertEqual(reflectedDirective.arguments["headingText"]?.required, true) + XCTAssertEqual(reflectedDirective.arguments["headingText"]?.labelDisplayName, "_ headingText") + XCTAssertEqual(reflectedDirective.arguments["headingText"]?.propertyLabel, "headingText") + } func testReflectMetadataDirective() { let reflectedDirective = DirectiveMirror(reflecting: Metadata.self).reflectedDirective @@ -39,7 +52,7 @@ class DirectiveMirrorTests: XCTestCase { XCTAssertFalse(reflectedDirective.allowsMarkup) XCTAssert(reflectedDirective.arguments.isEmpty) - XCTAssertEqual(reflectedDirective.childDirectives.count, 10) + XCTAssertEqual(reflectedDirective.childDirectives.count, 11) XCTAssertEqual( reflectedDirective.childDirectives["DocumentationExtension"]?.propertyLabel, diff --git a/Tests/SwiftDocCTests/Semantics/MetadataTests.swift b/Tests/SwiftDocCTests/Semantics/MetadataTests.swift index e626db475c..64051c6542 100644 --- a/Tests/SwiftDocCTests/Semantics/MetadataTests.swift +++ b/Tests/SwiftDocCTests/Semantics/MetadataTests.swift @@ -130,6 +130,23 @@ class MetadataTests: XCTestCase { XCTAssertEqual(metadata?.displayName?.name, "Custom Name") } + + func testTitleHeadingSupport() throws { + let source = """ + @Metadata { + @TitleHeading("Custom Heading") + } + """ + let document = Document(parsing: source, options: .parseBlockDirectives) + let directive = document.child(at: 0)! as! BlockDirective + let (bundle, context) = try testBundleAndContext(named: "TestBundle") + var problems = [Problem]() + let metadata = Metadata(from: directive, source: nil, for: bundle, in: context, problems: &problems) + XCTAssertNotNil(metadata) + XCTAssert(problems.isEmpty, "There shouldn't be any problems. Got:\n\(problems.map { $0.diagnostic.summary })") + + XCTAssertEqual(metadata?.titleHeading?.headingText, "Custom Heading") + } func testCustomMetadataSupport() throws { let source = """ @@ -231,6 +248,55 @@ class MetadataTests: XCTestCase { XCTAssertEqual(solution.replacements.last?.range, SourceLocation(line: 1, column: 1, source: nil) ..< SourceLocation(line: 1, column: 16, source: nil)) XCTAssertEqual(solution.replacements.last?.replacement, "# Custom Name") } + + func testSymbolArticleSupportsMetadataTitleHeading() throws { + let source = """ + # ``SomeSymbol`` + + @Metadata { + @TitleHeading("Custom Heading") + } + + The abstract of this documentation extension + """ + let document = Document(parsing: source, options: [.parseBlockDirectives, .parseSymbolLinks]) + let (bundle, context) = try testBundleAndContext(named: "TestBundle") + var problems = [Problem]() + let article = Article(from: document, source: nil, for: bundle, in: context, problems: &problems) + XCTAssertNotNil(article, "An Article value can be created with a Metadata child with a TitleHeading child.") + XCTAssertNotNil(article?.metadata?.titleHeading, "The Article has the parsed TitleHeading metadata.") + + XCTAssert(problems.isEmpty, "There shouldn't be any problems. Got:\n\(problems.map { $0.diagnostic.summary })") + + var analyzer = SemanticAnalyzer(source: nil, context: context, bundle: bundle) + _ = analyzer.visit(document) + XCTAssert(analyzer.problems.isEmpty, "Expected no problems. Got:\n \(DiagnosticConsoleWriter.formattedDescription(for: analyzer.problems))") + } + + func testArticleSupportsMetadataTitleHeading() throws { + let source = """ + # Article title + + @Metadata { + @TitleHeading("Custom Heading") + } + + The abstract of this documentation extension + """ + let document = Document(parsing: source, options: [.parseBlockDirectives, .parseSymbolLinks]) + let (bundle, context) = try testBundleAndContext(named: "TestBundle") + var problems = [Problem]() + let article = Article(from: document, source: nil, for: bundle, in: context, problems: &problems) + XCTAssertNotNil(article, "An Article value can be created with a Metadata child with a TitleHeading child.") + XCTAssertNotNil(article?.metadata?.titleHeading, "The Article has the parsed TitleHeading metadata.") + XCTAssertEqual(article?.metadata?.titleHeading?.headingText, "Custom Heading") + + XCTAssert(problems.isEmpty, "There shouldn't be any problems. Got:\n\(problems.map { $0.diagnostic.summary })") + + var analyzer = SemanticAnalyzer(source: nil, context: context, bundle: bundle) + _ = analyzer.visit(document) + XCTAssert(analyzer.problems.isEmpty, "Expected no problems. Got:\n \(DiagnosticConsoleWriter.formattedDescription(for: analyzer.problems))") + } func testDuplicateMetadata() throws { let source = """ From 3d6ff9341c2ce1a9813db7abc7d28743e505a3a0 Mon Sep 17 00:00:00 2001 From: Emily Chen Date: Fri, 9 Jun 2023 11:58:20 -0700 Subject: [PATCH 04/16] updated documentation --- .../DocCDocumentation.docc/DocC.symbols.json | 142 ++++++++++++++++++ 1 file changed, 142 insertions(+) diff --git a/Sources/docc/DocCDocumentation.docc/DocC.symbols.json b/Sources/docc/DocCDocumentation.docc/DocC.symbols.json index e76aa2e00f..66068bb210 100644 --- a/Sources/docc/DocCDocumentation.docc/DocC.symbols.json +++ b/Sources/docc/DocCDocumentation.docc/DocC.symbols.json @@ -2963,6 +2963,9 @@ }, { "text" : "- ``SupportedLanguage``" + }, + { + "text" : "- ``TitleHeading``" } ] }, @@ -5058,6 +5061,145 @@ "TechnologyRoot" ] }, + { + "accessLevel" : "public", + "declarationFragments" : [ + { + "kind" : "typeIdentifier", + "spelling" : "@" + }, + { + "kind" : "typeIdentifier", + "spelling" : "TitleHeading" + }, + { + "kind" : "text", + "spelling" : "(" + }, + { + "kind" : "text", + "spelling" : "_ " + }, + { + "kind" : "identifier", + "spelling" : "headingText" + }, + { + "kind" : "text", + "spelling" : ": " + }, + { + "kind" : "typeIdentifier", + "spelling" : "String" + }, + { + "kind" : "text", + "spelling" : ")" + } + ], + "docComment" : { + "lines" : [ + { + "text" : "A directive for customizing the text of a page-title heading (aka an eyebrow or kick)." + }, + { + "text" : "" + }, + { + "text" : "@TitleHeading accepts an unnamed parameter containing containing the page-title’s heading text." + }, + { + "text" : "" + }, + { + "text" : "This directive is only valid within a top-level ``Metadata`` directive:" + }, + { + "text" : "```markdown" + }, + { + "text" : "@Metadata {" + }, + { + "text" : " @TitleHeading(\"Release Notes\")" + }, + { + "text" : "}" + }, + { + "text" : "```" + }, + { + "text" : "- Parameters:" + }, + { + "text" : " - headingText: An unnamed parameter containing containing the page-title’s heading text." + }, + { + "text" : " **(required)**" + } + ] + }, + "identifier" : { + "interfaceLanguage" : "swift", + "precise" : "__docc_universal_symbol_reference_$TitleHeading" + }, + "kind" : { + "displayName" : "Directive", + "identifier" : "class" + }, + "names" : { + "navigator" : [ + { + "kind" : "attribute", + "spelling" : "@" + }, + { + "kind" : "identifier", + "preciseIdentifier" : "__docc_universal_symbol_reference_$TitleHeading", + "spelling" : "TitleHeading" + } + ], + "subHeading" : [ + { + "kind" : "identifier", + "spelling" : "@" + }, + { + "kind" : "identifier", + "spelling" : "TitleHeading" + }, + { + "kind" : "text", + "spelling" : "(" + }, + { + "kind" : "text", + "spelling" : "_ " + }, + { + "kind" : "identifier", + "spelling" : "headingText" + }, + { + "kind" : "text", + "spelling" : ": " + }, + { + "kind" : "typeIdentifier", + "spelling" : "String" + }, + { + "kind" : "text", + "spelling" : ")" + } + ], + "title" : "TitleHeading" + }, + "pathComponents" : [ + "TitleHeading" + ] + }, { "accessLevel" : "public", "declarationFragments" : [ From d3b24b97eafb956cfa6b134933e8f928f74f7dd8 Mon Sep 17 00:00:00 2001 From: Emily Chen Date: Fri, 9 Jun 2023 13:17:57 -0700 Subject: [PATCH 05/16] Update Documentation Co-authored-by: Ethan Kusters --- Sources/SwiftDocC/Semantics/Metadata/TitleHeading.swift | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Sources/SwiftDocC/Semantics/Metadata/TitleHeading.swift b/Sources/SwiftDocC/Semantics/Metadata/TitleHeading.swift index 9762b4cfe1..16c547669e 100644 --- a/Sources/SwiftDocC/Semantics/Metadata/TitleHeading.swift +++ b/Sources/SwiftDocC/Semantics/Metadata/TitleHeading.swift @@ -11,7 +11,7 @@ import Foundation import Markdown -/// A directive for customizing the text of a page-title heading (aka an eyebrow or kick). +/// A directive for customizing the text of a page's title heading. /// /// @TitleHeading accepts an unnamed parameter containing containing the page-title’s heading text. /// From 0ed55ba8dc496d7cea085114809d8eadbb204263 Mon Sep 17 00:00:00 2001 From: Emily Chen Date: Fri, 9 Jun 2023 13:54:26 -0700 Subject: [PATCH 06/16] resolve PR comments --- .../Rendering/RenderNode/RenderMetadata.swift | 2 +- .../Semantics/Metadata/TitleHeading.swift | 6 ++- .../DocCDocumentation.docc/DocC.symbols.json | 10 ++++- .../API Reference Syntax/TitleHeading.md | 38 +++++++++++++++++++ 4 files changed, 51 insertions(+), 5 deletions(-) create mode 100644 Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/TitleHeading.md diff --git a/Sources/SwiftDocC/Model/Rendering/RenderNode/RenderMetadata.swift b/Sources/SwiftDocC/Model/Rendering/RenderNode/RenderMetadata.swift index e6eca99361..fd78269137 100644 --- a/Sources/SwiftDocC/Model/Rendering/RenderNode/RenderMetadata.swift +++ b/Sources/SwiftDocC/Model/Rendering/RenderNode/RenderMetadata.swift @@ -93,7 +93,7 @@ public struct RenderMetadata: VariantContainer { /// The variants of the title. public var titleVariants: VariantCollection = .init(defaultValue: nil) - + /// An identifier for a symbol generated externally. public var externalID: String? { get { getVariantDefaultValue(keyPath: \.externalIDVariants) } diff --git a/Sources/SwiftDocC/Semantics/Metadata/TitleHeading.swift b/Sources/SwiftDocC/Semantics/Metadata/TitleHeading.swift index 16c547669e..f91c1c3d3d 100644 --- a/Sources/SwiftDocC/Semantics/Metadata/TitleHeading.swift +++ b/Sources/SwiftDocC/Semantics/Metadata/TitleHeading.swift @@ -13,7 +13,9 @@ import Markdown /// A directive for customizing the text of a page's title heading. /// -/// @TitleHeading accepts an unnamed parameter containing containing the page-title’s heading text. +/// The ``headingText`` property will override the page's default title heading. +/// +/// @TitleHeading accepts an unnamed parameter containing containing the page's title heading. /// /// This directive is only valid within a top-level ``Metadata`` directive: /// ```markdown @@ -36,4 +38,4 @@ public final class TitleHeading: Semantic, AutomaticDirectiveConvertible { init(originalMarkup: BlockDirective) { self.originalMarkup = originalMarkup } -} \ No newline at end of file +} diff --git a/Sources/docc/DocCDocumentation.docc/DocC.symbols.json b/Sources/docc/DocCDocumentation.docc/DocC.symbols.json index 66068bb210..8b015c7e34 100644 --- a/Sources/docc/DocCDocumentation.docc/DocC.symbols.json +++ b/Sources/docc/DocCDocumentation.docc/DocC.symbols.json @@ -5100,13 +5100,19 @@ "docComment" : { "lines" : [ { - "text" : "A directive for customizing the text of a page-title heading (aka an eyebrow or kick)." + "text" : "A directive for customizing the text of a page's title heading." }, { "text" : "" }, { - "text" : "@TitleHeading accepts an unnamed parameter containing containing the page-title’s heading text." + "text" : "The ``headingText`` property will override the page's default title heading." + }, + { + "text" : "" + }, + { + "text" : "@TitleHeading accepts an unnamed parameter containing containing the page's title heading." }, { "text" : "" diff --git a/Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/TitleHeading.md b/Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/TitleHeading.md new file mode 100644 index 0000000000..e06983e005 --- /dev/null +++ b/Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/TitleHeading.md @@ -0,0 +1,38 @@ +# ``docc/TitleHeading`` + +Configures a symbol's documentation page and any references to that page to show a custom title heading instead of the default (page kind). + +@Metadata { + @DocumentationExtension(mergeBehavior: override) +} + +- Parameters: + - headingText: The text for the custom title heading. + +## Overview + +Place the `TitleHeading` directive within a `Metadata` directive to configure a symbol's documentation page to show a custom title heading. This allows for the creation of custom kinds of pages beyond just articles. + +A title heading is also known as a page eyebrow or kicker. + +``` +# ``SlothCreator`` + +@Metadata { + @TitleHeading("Release Notes") +} +``` + +A custom title heading appears in place of the page kind at the top of the page. + +> Note: Customizing the title heading of a symbol page doesn't alter the page's URL. + +> Note: Adding a `TitleHeading` directive to a non-symbol page results in a warning. + +### Containing Elements + +The following items can include a title heading element: + +- ``Metadata`` + + From ed2690bf71d82941a804c5c51081ff770dbb6c56 Mon Sep 17 00:00:00 2001 From: Emily Chen Date: Fri, 9 Jun 2023 13:55:17 -0700 Subject: [PATCH 07/16] Update Metadata.md Co-authored-by: Ethan Kusters --- .../Reference Syntax/API Reference Syntax/Metadata.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/Metadata.md b/Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/Metadata.md index b0cc478f59..66973d1c53 100644 --- a/Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/Metadata.md +++ b/Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/Metadata.md @@ -30,7 +30,7 @@ Use the `Metadata` directive with the ``DisplayName`` directive to configure a s } ``` -Use the `Metadata` directive with the ``TitleHeading`` directive to configure the text of a page-title heading (also known as an eyebrow or kick). +Use the `Metadata` directive with the ``TitleHeading`` directive to configure the text of a page's title heading. ``` # ``SlothCreator`` From 98307183c13e0abb3dbbce0c0f0453abb9a53e41 Mon Sep 17 00:00:00 2001 From: Emily Chen Date: Fri, 9 Jun 2023 14:26:00 -0700 Subject: [PATCH 08/16] resolve PR comments --- Tests/SwiftDocCTests/Rendering/RenderNodeTranslatorTests.swift | 3 +++ Tests/SwiftDocCTests/Semantics/MetadataTests.swift | 1 + .../Test Bundles/BookLikeContent.docc/MyArticle.md | 1 + 3 files changed, 5 insertions(+) diff --git a/Tests/SwiftDocCTests/Rendering/RenderNodeTranslatorTests.swift b/Tests/SwiftDocCTests/Rendering/RenderNodeTranslatorTests.swift index 91f90b2296..c7d64069e9 100644 --- a/Tests/SwiftDocCTests/Rendering/RenderNodeTranslatorTests.swift +++ b/Tests/SwiftDocCTests/Rendering/RenderNodeTranslatorTests.swift @@ -1225,6 +1225,9 @@ class RenderNodeTranslatorTests: XCTestCase { roundTrippedArticle.metadata.color?.standardColorIdentifier, "yellow" ) + + XCTAssertEqual(roundTrippedArticle.metadata.roleHeading, "Book-Like Content") + XCTAssertEqual(roundTrippedArticle.metadata.role, "article") } func testPageColorMetadataInSymbolExtension() throws { diff --git a/Tests/SwiftDocCTests/Semantics/MetadataTests.swift b/Tests/SwiftDocCTests/Semantics/MetadataTests.swift index 64051c6542..b378982683 100644 --- a/Tests/SwiftDocCTests/Semantics/MetadataTests.swift +++ b/Tests/SwiftDocCTests/Semantics/MetadataTests.swift @@ -265,6 +265,7 @@ class MetadataTests: XCTestCase { let article = Article(from: document, source: nil, for: bundle, in: context, problems: &problems) XCTAssertNotNil(article, "An Article value can be created with a Metadata child with a TitleHeading child.") XCTAssertNotNil(article?.metadata?.titleHeading, "The Article has the parsed TitleHeading metadata.") + XCTAssertNotNil(article?.metadata?.titleHeading?.headingText, "Custom Heading") XCTAssert(problems.isEmpty, "There shouldn't be any problems. Got:\n\(problems.map { $0.diagnostic.summary })") diff --git a/Tests/SwiftDocCTests/Test Bundles/BookLikeContent.docc/MyArticle.md b/Tests/SwiftDocCTests/Test Bundles/BookLikeContent.docc/MyArticle.md index 64f4f99d54..5eecf0c9f2 100644 --- a/Tests/SwiftDocCTests/Test Bundles/BookLikeContent.docc/MyArticle.md +++ b/Tests/SwiftDocCTests/Test Bundles/BookLikeContent.docc/MyArticle.md @@ -7,6 +7,7 @@ This is the abstract of my article. Nice! @PageImage(source: "figure1", alt: "An example figure.", purpose: card) @CustomMetadata(key: "country", value: "Belgium") @PageColor(yellow) + @TitleHeading("Book-Like Content") } @Row(numberOfColumns: 8) { From af81d1d14b69d0b95ef9b75c43526a623a404884 Mon Sep 17 00:00:00 2001 From: Emily Chen Date: Fri, 9 Jun 2023 15:31:30 -0700 Subject: [PATCH 09/16] Update TitleHeading.md Co-authored-by: Ethan Kusters --- .../Reference Syntax/API Reference Syntax/TitleHeading.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/TitleHeading.md b/Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/TitleHeading.md index e06983e005..60a3318cd8 100644 --- a/Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/TitleHeading.md +++ b/Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/TitleHeading.md @@ -24,11 +24,6 @@ A title heading is also known as a page eyebrow or kicker. ``` A custom title heading appears in place of the page kind at the top of the page. - -> Note: Customizing the title heading of a symbol page doesn't alter the page's URL. - -> Note: Adding a `TitleHeading` directive to a non-symbol page results in a warning. - ### Containing Elements The following items can include a title heading element: From 15f6f14c5bcdf99fe3d3d7bf894243a9596319d8 Mon Sep 17 00:00:00 2001 From: Emily Chen Date: Fri, 9 Jun 2023 15:31:58 -0700 Subject: [PATCH 10/16] Update TitleHeading.md Co-authored-by: Ethan Kusters --- .../Reference Syntax/API Reference Syntax/TitleHeading.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/TitleHeading.md b/Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/TitleHeading.md index 60a3318cd8..b12d4f0ae5 100644 --- a/Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/TitleHeading.md +++ b/Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/TitleHeading.md @@ -28,6 +28,8 @@ A custom title heading appears in place of the page kind at the top of the page. The following items can include a title heading element: -- ``Metadata`` +@Links(visualStyle: list) { + - ``Metadata`` +} From 13b2415b135730d0ccb5e4ad0d220ddef6444bb4 Mon Sep 17 00:00:00 2001 From: Emily Chen Date: Fri, 9 Jun 2023 15:32:27 -0700 Subject: [PATCH 11/16] Update Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/TitleHeading.md Co-authored-by: Ethan Kusters --- .../Reference Syntax/API Reference Syntax/TitleHeading.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/TitleHeading.md b/Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/TitleHeading.md index b12d4f0ae5..4e600d3bd1 100644 --- a/Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/TitleHeading.md +++ b/Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/TitleHeading.md @@ -11,7 +11,7 @@ Configures a symbol's documentation page and any references to that page to show ## Overview -Place the `TitleHeading` directive within a `Metadata` directive to configure a symbol's documentation page to show a custom title heading. This allows for the creation of custom kinds of pages beyond just articles. +Place the `TitleHeading` directive within a `Metadata` directive to configure a documentation page to show a custom title heading. Custom title headings, along with custom [page icons](doc:PageImage) and [page colors](doc:PageColor), allow for the creation of custom kinds of pages beyond just articles. A title heading is also known as a page eyebrow or kicker. From 8a6e9bca5d1d93460cbf48f755fddc17fa3cd091 Mon Sep 17 00:00:00 2001 From: Emily Chen Date: Fri, 9 Jun 2023 15:40:16 -0700 Subject: [PATCH 12/16] resolved more PR comments --- .../Rendering/RenderNodeTranslatorTests.swift | 22 ++++++++++++++++ .../Semantics/MetadataTests.swift | 25 ------------------- .../TestBed.md | 1 + 3 files changed, 23 insertions(+), 25 deletions(-) diff --git a/Tests/SwiftDocCTests/Rendering/RenderNodeTranslatorTests.swift b/Tests/SwiftDocCTests/Rendering/RenderNodeTranslatorTests.swift index c7d64069e9..d54ebede20 100644 --- a/Tests/SwiftDocCTests/Rendering/RenderNodeTranslatorTests.swift +++ b/Tests/SwiftDocCTests/Rendering/RenderNodeTranslatorTests.swift @@ -1250,4 +1250,26 @@ class RenderNodeTranslatorTests: XCTestCase { let roundTrippedSymbol = try JSONDecoder().decode(RenderNode.self, from: encodedSymbol) XCTAssertEqual(roundTrippedSymbol.metadata.color?.standardColorIdentifier, "purple") } + + func testTitleHeadingMetadataInSymbolExtension() throws { + let (bundle, context) = try testBundleAndContext(named: "MixedManualAutomaticCuration") + let reference = ResolvedTopicReference( + bundleIdentifier: bundle.identifier, + path: "/documentation/TestBed", + sourceLanguage: .swift + ) + let symbol = try XCTUnwrap(context.entity(with: reference).semantic as? Symbol) + var translator = RenderNodeTranslator( + context: context, + bundle: bundle, + identifier: reference, + source: nil + ) + let renderNode = try XCTUnwrap(translator.visitSymbol(symbol) as? RenderNode) + + let encodedSymbol = try JSONEncoder().encode(renderNode) + let roundTrippedSymbol = try JSONDecoder().decode(RenderNode.self, from: encodedSymbol) + XCTAssertEqual(roundTrippedSymbol.metadata.roleHeading, "TestBed Notes") + XCTAssertEqual(roundTrippedSymbol.metadata.role, "collection") + } } diff --git a/Tests/SwiftDocCTests/Semantics/MetadataTests.swift b/Tests/SwiftDocCTests/Semantics/MetadataTests.swift index b378982683..12293ddd80 100644 --- a/Tests/SwiftDocCTests/Semantics/MetadataTests.swift +++ b/Tests/SwiftDocCTests/Semantics/MetadataTests.swift @@ -249,31 +249,6 @@ class MetadataTests: XCTestCase { XCTAssertEqual(solution.replacements.last?.replacement, "# Custom Name") } - func testSymbolArticleSupportsMetadataTitleHeading() throws { - let source = """ - # ``SomeSymbol`` - - @Metadata { - @TitleHeading("Custom Heading") - } - - The abstract of this documentation extension - """ - let document = Document(parsing: source, options: [.parseBlockDirectives, .parseSymbolLinks]) - let (bundle, context) = try testBundleAndContext(named: "TestBundle") - var problems = [Problem]() - let article = Article(from: document, source: nil, for: bundle, in: context, problems: &problems) - XCTAssertNotNil(article, "An Article value can be created with a Metadata child with a TitleHeading child.") - XCTAssertNotNil(article?.metadata?.titleHeading, "The Article has the parsed TitleHeading metadata.") - XCTAssertNotNil(article?.metadata?.titleHeading?.headingText, "Custom Heading") - - XCTAssert(problems.isEmpty, "There shouldn't be any problems. Got:\n\(problems.map { $0.diagnostic.summary })") - - var analyzer = SemanticAnalyzer(source: nil, context: context, bundle: bundle) - _ = analyzer.visit(document) - XCTAssert(analyzer.problems.isEmpty, "Expected no problems. Got:\n \(DiagnosticConsoleWriter.formattedDescription(for: analyzer.problems))") - } - func testArticleSupportsMetadataTitleHeading() throws { let source = """ # Article title diff --git a/Tests/SwiftDocCTests/Test Bundles/MixedManualAutomaticCuration.docc/TestBed.md b/Tests/SwiftDocCTests/Test Bundles/MixedManualAutomaticCuration.docc/TestBed.md index ba8405f1a7..0d3ce9538c 100644 --- a/Tests/SwiftDocCTests/Test Bundles/MixedManualAutomaticCuration.docc/TestBed.md +++ b/Tests/SwiftDocCTests/Test Bundles/MixedManualAutomaticCuration.docc/TestBed.md @@ -2,6 +2,7 @@ @Metadata { @PageColor(purple) + @TitleHeading("TestBed Notes") } TestBed framework. From 2b3e8bf089d8e99998fad4746186dcde6441e173 Mon Sep 17 00:00:00 2001 From: Emily Chen Date: Fri, 9 Jun 2023 17:54:09 -0700 Subject: [PATCH 13/16] Update Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/TitleHeading.md Co-authored-by: Ethan Kusters --- .../Reference Syntax/API Reference Syntax/TitleHeading.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/TitleHeading.md b/Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/TitleHeading.md index 4e600d3bd1..dc366ea7f7 100644 --- a/Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/TitleHeading.md +++ b/Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/TitleHeading.md @@ -1,6 +1,6 @@ # ``docc/TitleHeading`` -Configures a symbol's documentation page and any references to that page to show a custom title heading instead of the default (page kind). +A directive that specifies a title heading for a given documentation page. @Metadata { @DocumentationExtension(mergeBehavior: override) From 67ffb698149a827171a095a30b0acf434ab5b875 Mon Sep 17 00:00:00 2001 From: Emily Chen Date: Fri, 9 Jun 2023 18:01:47 -0700 Subject: [PATCH 14/16] Update Sources/SwiftDocC/Semantics/Metadata/TitleHeading.swift Co-authored-by: Ethan Kusters --- Sources/SwiftDocC/Semantics/Metadata/TitleHeading.swift | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Sources/SwiftDocC/Semantics/Metadata/TitleHeading.swift b/Sources/SwiftDocC/Semantics/Metadata/TitleHeading.swift index f91c1c3d3d..48f36ca575 100644 --- a/Sources/SwiftDocC/Semantics/Metadata/TitleHeading.swift +++ b/Sources/SwiftDocC/Semantics/Metadata/TitleHeading.swift @@ -28,7 +28,7 @@ public final class TitleHeading: Semantic, AutomaticDirectiveConvertible { /// An unnamed parameter containing containing the page-title’s heading text. @DirectiveArgumentWrapped(name: .unnamed) - public var headingText: String + public var heading: String static var keyPaths: [String : AnyKeyPath] = [ "headingText" : \TitleHeading._headingText, From a685e0a12501e68c2291aefa16527efb833b0ad3 Mon Sep 17 00:00:00 2001 From: Emily Chen Date: Fri, 9 Jun 2023 18:02:00 -0700 Subject: [PATCH 15/16] Update Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/TitleHeading.md Co-authored-by: Ethan Kusters --- .../Reference Syntax/API Reference Syntax/TitleHeading.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/TitleHeading.md b/Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/TitleHeading.md index dc366ea7f7..e1bfe748e0 100644 --- a/Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/TitleHeading.md +++ b/Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/TitleHeading.md @@ -7,7 +7,7 @@ A directive that specifies a title heading for a given documentation page. } - Parameters: - - headingText: The text for the custom title heading. + - heading: The text for the custom title heading. ## Overview From a944686886179df8f9ef5637f31c889292f58e33 Mon Sep 17 00:00:00 2001 From: Emily Chen Date: Fri, 9 Jun 2023 18:27:43 -0700 Subject: [PATCH 16/16] change headingText property to heading --- .../SwiftDocC/Model/Rendering/RenderNodeTranslator.swift | 4 ++-- Sources/SwiftDocC/Semantics/Metadata/TitleHeading.swift | 4 ++-- Sources/docc/DocCDocumentation.docc/DocC.symbols.json | 8 ++++---- .../DirectiveInfrastructure/DirectiveMirrorTests.swift | 8 ++++---- Tests/SwiftDocCTests/Semantics/MetadataTests.swift | 4 ++-- 5 files changed, 14 insertions(+), 14 deletions(-) diff --git a/Sources/SwiftDocC/Model/Rendering/RenderNodeTranslator.swift b/Sources/SwiftDocC/Model/Rendering/RenderNodeTranslator.swift index 225e06f971..f4cd55d3ce 100644 --- a/Sources/SwiftDocC/Model/Rendering/RenderNodeTranslator.swift +++ b/Sources/SwiftDocC/Model/Rendering/RenderNodeTranslator.swift @@ -848,7 +848,7 @@ public struct RenderNodeTranslator: SemanticVisitor { } if let titleHeading = article.metadata?.titleHeading { - node.metadata.roleHeading = titleHeading.headingText + node.metadata.roleHeading = titleHeading.heading } collectedTopicReferences.append(contentsOf: contentCompiler.collectedTopicReferences) @@ -1253,7 +1253,7 @@ public struct RenderNodeTranslator: SemanticVisitor { } if let titleHeading = documentationNode.metadata?.titleHeading { - node.metadata.roleHeadingVariants = VariantCollection(defaultValue: titleHeading.headingText) + node.metadata.roleHeadingVariants = VariantCollection(defaultValue: titleHeading.heading) } node.metadata.symbolKindVariants = VariantCollection(from: symbol.kindVariants) { _, kindVariants in diff --git a/Sources/SwiftDocC/Semantics/Metadata/TitleHeading.swift b/Sources/SwiftDocC/Semantics/Metadata/TitleHeading.swift index 48f36ca575..fcce0dc07f 100644 --- a/Sources/SwiftDocC/Semantics/Metadata/TitleHeading.swift +++ b/Sources/SwiftDocC/Semantics/Metadata/TitleHeading.swift @@ -13,7 +13,7 @@ import Markdown /// A directive for customizing the text of a page's title heading. /// -/// The ``headingText`` property will override the page's default title heading. +/// The ``heading`` property will override the page's default title heading. /// /// @TitleHeading accepts an unnamed parameter containing containing the page's title heading. /// @@ -31,7 +31,7 @@ public final class TitleHeading: Semantic, AutomaticDirectiveConvertible { public var heading: String static var keyPaths: [String : AnyKeyPath] = [ - "headingText" : \TitleHeading._headingText, + "heading" : \TitleHeading._heading, ] @available(*, deprecated, message: "Do not call directly. Required for 'AutomaticDirectiveConvertible'.") diff --git a/Sources/docc/DocCDocumentation.docc/DocC.symbols.json b/Sources/docc/DocCDocumentation.docc/DocC.symbols.json index 8b015c7e34..666125b652 100644 --- a/Sources/docc/DocCDocumentation.docc/DocC.symbols.json +++ b/Sources/docc/DocCDocumentation.docc/DocC.symbols.json @@ -5082,7 +5082,7 @@ }, { "kind" : "identifier", - "spelling" : "headingText" + "spelling" : "heading" }, { "kind" : "text", @@ -5106,7 +5106,7 @@ "text" : "" }, { - "text" : "The ``headingText`` property will override the page's default title heading." + "text" : "The ``heading`` property will override the page's default title heading." }, { "text" : "" @@ -5139,7 +5139,7 @@ "text" : "- Parameters:" }, { - "text" : " - headingText: An unnamed parameter containing containing the page-title’s heading text." + "text" : " - heading: An unnamed parameter containing containing the page-title’s heading text." }, { "text" : " **(required)**" @@ -5185,7 +5185,7 @@ }, { "kind" : "identifier", - "spelling" : "headingText" + "spelling" : "heading" }, { "kind" : "text", diff --git a/Tests/SwiftDocCTests/Semantics/DirectiveInfrastructure/DirectiveMirrorTests.swift b/Tests/SwiftDocCTests/Semantics/DirectiveInfrastructure/DirectiveMirrorTests.swift index ab836b2a39..bf303cf5c5 100644 --- a/Tests/SwiftDocCTests/Semantics/DirectiveInfrastructure/DirectiveMirrorTests.swift +++ b/Tests/SwiftDocCTests/Semantics/DirectiveInfrastructure/DirectiveMirrorTests.swift @@ -39,10 +39,10 @@ class DirectiveMirrorTests: XCTestCase { XCTAssertFalse(reflectedDirective.allowsMarkup) XCTAssertEqual(reflectedDirective.arguments.count, 1) - XCTAssertEqual(reflectedDirective.arguments["headingText"]?.unnamed, true) - XCTAssertEqual(reflectedDirective.arguments["headingText"]?.required, true) - XCTAssertEqual(reflectedDirective.arguments["headingText"]?.labelDisplayName, "_ headingText") - XCTAssertEqual(reflectedDirective.arguments["headingText"]?.propertyLabel, "headingText") + XCTAssertEqual(reflectedDirective.arguments["heading"]?.unnamed, true) + XCTAssertEqual(reflectedDirective.arguments["heading"]?.required, true) + XCTAssertEqual(reflectedDirective.arguments["heading"]?.labelDisplayName, "_ heading") + XCTAssertEqual(reflectedDirective.arguments["heading"]?.propertyLabel, "heading") } func testReflectMetadataDirective() { diff --git a/Tests/SwiftDocCTests/Semantics/MetadataTests.swift b/Tests/SwiftDocCTests/Semantics/MetadataTests.swift index 12293ddd80..b55301b4bc 100644 --- a/Tests/SwiftDocCTests/Semantics/MetadataTests.swift +++ b/Tests/SwiftDocCTests/Semantics/MetadataTests.swift @@ -145,7 +145,7 @@ class MetadataTests: XCTestCase { XCTAssertNotNil(metadata) XCTAssert(problems.isEmpty, "There shouldn't be any problems. Got:\n\(problems.map { $0.diagnostic.summary })") - XCTAssertEqual(metadata?.titleHeading?.headingText, "Custom Heading") + XCTAssertEqual(metadata?.titleHeading?.heading, "Custom Heading") } func testCustomMetadataSupport() throws { @@ -265,7 +265,7 @@ class MetadataTests: XCTestCase { let article = Article(from: document, source: nil, for: bundle, in: context, problems: &problems) XCTAssertNotNil(article, "An Article value can be created with a Metadata child with a TitleHeading child.") XCTAssertNotNil(article?.metadata?.titleHeading, "The Article has the parsed TitleHeading metadata.") - XCTAssertEqual(article?.metadata?.titleHeading?.headingText, "Custom Heading") + XCTAssertEqual(article?.metadata?.titleHeading?.heading, "Custom Heading") XCTAssert(problems.isEmpty, "There shouldn't be any problems. Got:\n\(problems.map { $0.diagnostic.summary })")