From 868cc740693b081b3a2d8e7e1813aeb4215b2d5d Mon Sep 17 00:00:00 2001 From: Ethan Kusters Date: Tue, 10 Jan 2023 16:49:20 -0800 Subject: [PATCH 1/2] Update swift-markdown to latest `main` MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Includes the following changes: commit b1622a0a0b747740839511b1387289bcf1c64b19 Author: Ethan Kusters Date: Mon Jan 9 17:42:46 2023 -0800 Adds the `seeAlso` aside “See Also” is a common kind of aside that folks parsing markdown may wish to consider. For Swift-DocC specifically, there is a lot of pre-DocC Swift documentation content that uses this style of callout: ``` - SeeAlso: ``` In order to gracefully transition this content over to Swift-DocC style asides, we should add support for them. commit 87ae1a8fa9180b85630c7b41ddd5aa40ffc87ce3 Author: Ashley Garland Date: Tue Dec 6 20:23:49 2022 -0800 Adopt more snippets Add snippets for the following areas: - Parsing - Querying - Walkers, Rewriters, and Visitors - Formatting Add a link to the top-level page. Add an article which inlines all of the snippets in one place for quick reference. rdar://103054461 commit 3a631f4d4b0e9c80004b8555bcb629c898e8089f Author: Tim Triemstra Date: Fri Dec 2 13:15:36 2022 -0800 Fixed the snippets support to use the new standard comment structure, and the @Snippet references use the full path to the snippet file commit 0d04722bafe7c6c29c485e4bdaa2235b879cc7e7 Author: Ashley Garland Date: Tue Mar 29 23:18:49 2022 -0700 Example usage of snippets for Swift Evolution commit 7dd6c526c9184fd7fabdda592167f305727b515e Author: Christian Selig Date: Tue Nov 29 12:42:21 2022 -0400 Add support for custom attributes (#25) rdar://96536586 --- Package.resolved | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Package.resolved b/Package.resolved index 25c17d9388..b9f79ac71d 100644 --- a/Package.resolved +++ b/Package.resolved @@ -60,7 +60,7 @@ "repositoryURL": "https://github.com/apple/swift-markdown.git", "state": { "branch": "main", - "revision": "d491147940587dbadfb3472354f4d0c6e063e061", + "revision": "4a5dd44f1fb703f853df85a928492dfd1c98aa25", "version": null } }, From 4f00da96101f2ca0eff20c21efbc49c1ff7a61bd Mon Sep 17 00:00:00 2001 From: Ethan Kusters Date: Tue, 10 Jan 2023 17:56:16 -0800 Subject: [PATCH 2/2] Support legacy `- seealso:` callout asides MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit There’s a lot of existing Swift documentation content that uses the legacy `- seealso:` style aside: ``` - SeeAlso: This other content. ``` While Swift-DocC has always supported a number of these legacy asides like: ``` - Experiment: Lorem ipsum. - Tip: Lorem ipsum ``` it doesn’t currently support `SeeAlso` which causes breakage when migrating existing Swift doc comments over to Swift-DocC. This resolves the issue. rdar://55141543 --- .../Content/RenderBlockContent.swift | 12 ++++------ .../Model/SemaToRenderNodeTests.swift | 6 +++++ .../Test Resources/Asides.symbols.json | 24 +++++++++++++++++++ 3 files changed, 35 insertions(+), 7 deletions(-) diff --git a/Sources/SwiftDocC/Model/Rendering/Content/RenderBlockContent.swift b/Sources/SwiftDocC/Model/Rendering/Content/RenderBlockContent.swift index 5d7497ff4d..61eb2c23d6 100644 --- a/Sources/SwiftDocC/Model/Rendering/Content/RenderBlockContent.swift +++ b/Sources/SwiftDocC/Model/Rendering/Content/RenderBlockContent.swift @@ -295,11 +295,9 @@ public enum RenderBlockContent: Equatable { /// A type the describes an aside style. public struct AsideStyle: Codable, Equatable { - private static let specialDisplayNames: [String: String] = [ - "nonmutatingvariant": "Non-Mutating Variant", - "mutatingvariant": "Mutating Variant", - "todo": "To Do", - ] + private static let knownDisplayNames: [String: String] = Dictionary( + uniqueKeysWithValues: Markdown.Aside.Kind.allCases.map { ($0.rawValue.lowercased(), $0.displayName) } + ) /// Returns a Boolean value indicating whether two aside styles are equal. /// @@ -317,7 +315,7 @@ public enum RenderBlockContent: Equatable { /// The heading text to use when rendering this style of aside. public var displayName: String { - if let value = Self.specialDisplayNames[rawValue.lowercased()] { + if let value = Self.knownDisplayNames[rawValue.lowercased()] { return value } else if rawValue.contains(where: \.isUppercase) { // If any character is upper-cased, assume the content has @@ -363,7 +361,7 @@ public enum RenderBlockContent: Equatable { /// Creates an aside style with the specified display name. /// - Parameter displayName: The heading text to use when rendering this style of aside. public init(displayName: String) { - self.rawValue = Self.specialDisplayNames.first(where: { $0.value == displayName })?.key ?? displayName + self.rawValue = Self.knownDisplayNames.first(where: { $0.value == displayName })?.key ?? displayName } /// Encodes the aside style into the specified encoder. diff --git a/Tests/SwiftDocCTests/Model/SemaToRenderNodeTests.swift b/Tests/SwiftDocCTests/Model/SemaToRenderNodeTests.swift index 4753ccb180..2d3b483858 100644 --- a/Tests/SwiftDocCTests/Model/SemaToRenderNodeTests.swift +++ b/Tests/SwiftDocCTests/Model/SemaToRenderNodeTests.swift @@ -2454,6 +2454,8 @@ Document .aside(.init(style: .init(rawValue: "Since"), content: [.paragraph(.init(inlineContent: [.text("The beginning of time.")]))])), .aside(.init(style: .init(rawValue: "Todo"), content: [.paragraph(.init(inlineContent: [.text("This needs work.")]))])), .aside(.init(style: .init(rawValue: "Version"), content: [.paragraph(.init(inlineContent: [.text("3.1.4")]))])), + .aside(.init(style: .init(rawValue: "SeeAlso"), content: [.paragraph(.init(inlineContent: [.text("This other thing.")]))])), + .aside(.init(style: .init(rawValue: "SeeAlso"), content: [.paragraph(.init(inlineContent: [.text("And this other thing.")]))])), .aside(.init(style: .init(rawValue: "Throws"), content: [.paragraph(.init(inlineContent: [.text("A serious error.")]))])), ] @@ -2996,6 +2998,10 @@ Document "content": [{"type":"paragraph", "inlineContent":[{"type":"text", "text":"This needs work."}]}]}, {"type":"aside", "style":"note", "name":"Version", "content": [{"type":"paragraph", "inlineContent":[{"type":"text", "text":"3.1.4"}]}]}, + {"type":"aside", "style":"note", "name":"See Also", + "content": [{"type":"paragraph", "inlineContent":[{"type":"text", "text":"This other thing."}]}]}, + {"type":"aside", "style":"note", "name":"See Also", + "content": [{"type":"paragraph", "inlineContent":[{"type":"text", "text":"And this other thing."}]}]}, {"type":"aside", "style":"note", "name":"Throws", "content": [{"type":"paragraph", "inlineContent":[{"type":"text", "text":"A serious error."}]}]} ] diff --git a/Tests/SwiftDocCTests/Test Resources/Asides.symbols.json b/Tests/SwiftDocCTests/Test Resources/Asides.symbols.json index f281294df4..99ecfb79a3 100644 --- a/Tests/SwiftDocCTests/Test Resources/Asides.symbols.json +++ b/Tests/SwiftDocCTests/Test Resources/Asides.symbols.json @@ -202,6 +202,18 @@ { "text": "" }, + { + "text": "> seealso: This other thing." + }, + { + "text": "" + }, + { + "text": "> SeeAlso: And this other thing." + }, + { + "text": "" + }, { "text": "> Throws: A serious error." } @@ -421,6 +433,18 @@ { "text": "" }, + { + "text": "- SeeAlso: This other thing." + }, + { + "text": "" + }, + { + "text": "- seealso: And this other thing." + }, + { + "text": "" + }, { "text": "- Throws: A serious error." }