Remove use of snippet groups (swiftlang#10)

* Remove use of snippet groups These are informal in the latest proposal revision and don't carry any meaning. It's now intended to group snippets via curation in DocC. * Update IntegrationTests/Tests/SnippetDocumentationGenerationTests.swift Co-authored-by: Ethan Kusters <[email protected]> Co-authored-by: Ethan Kusters <[email protected]>
scutliyizhen · Mar 31, 2022 · d836ef3 · d836ef3
1 parent 859caac
commit d836ef3
Show file tree

Hide file tree

Showing 6 changed files with 22 additions and 124 deletions.
diff --git a/IntegrationTests/Tests/SnippetDocumentationGenerationTests.swift b/IntegrationTests/Tests/SnippetDocumentationGenerationTests.swift
@@ -25,6 +25,10 @@ final class SnippetDocumentationGenerationTests: XCTestCase {
         XCTAssertEqual(
             Set(dataDirectoryContents.map(\.lastTwoPathComponents)),
             [
+                // REMOVEME: "documentation/packagewithsnippets.json"
+                // should disappear once the fix for 
+                // https://github.com/apple/swift-docc/pull/116 is available in CI.
+                "documentation/packagewithsnippets.json",
                 "documentation/library.json",
                 "library/beststruct.json",
                 "beststruct/best().json",

diff --git a/Sources/Snippets/Model/Snippet.swift b/Sources/Snippets/Model/Snippet.swift
@@ -21,9 +21,6 @@ public struct Snippet {
     /// The code to display as the snippet.
     public var presentationCode: String
 
-    /// The name of the owning group, if snippet is in a ``SnippetGroup``.
-    public var groupName: String? = nil
-
     /// The identifier of the snippet.
     public var identifier: String {
         return sourceFile.deletingPathExtension().lastPathComponent

diff --git a/Sources/Snippets/Model/SnippetGroup.swift b/Sources/Snippets/Model/SnippetGroup.swift
diff --git a/Sources/snippet-build/SnippetBuildCommand.swift b/Sources/snippet-build/SnippetBuildCommand.swift
@@ -29,41 +29,18 @@ struct SnippetBuildCommand {
     }
 
     func run() throws {
-        let snippetGroups = try loadSnippetsAndSnippetGroups(from: URL(fileURLWithPath: snippetsDir))
-
-        let totalSnippetCount = snippetGroups.reduce(0) { $0 + $1.snippets.count }
-        guard totalSnippetCount > 0 else {
-            return
-        }
-
-        let symbolGraphFilename = URL(fileURLWithPath: outputDir).appendingPathComponent("\(moduleName)-snippets.symbols.json")
-
-        try emitSymbolGraph(forSnippetGroups: snippetGroups, to: symbolGraphFilename, moduleName: moduleName)
+        let snippets = try loadSnippets(from: URL(fileURLWithPath: snippetsDir))
+        guard snippets.count > 0 else { return }
+        let symbolGraphFilename = URL(fileURLWithPath: outputDir)
+            .appendingPathComponent("\(moduleName)-snippets.symbols.json")
+        try emitSymbolGraph(for: snippets, to: symbolGraphFilename, moduleName: moduleName)
     }
 
-    func emitSymbolGraph(forSnippetGroups snippetGroups: [SnippetGroup], to emitFilename: URL, moduleName: String) throws {
-        var groups = [SymbolGraph.Symbol]()
-        var snippets = [SymbolGraph.Symbol]()
-        var relationships = [SymbolGraph.Relationship]()
-
-        for group in snippetGroups {
-            let groupSymbol = SymbolGraph.Symbol(group, packageName: moduleName)
-            let snippetSymbols = group.snippets.map {
-                SymbolGraph.Symbol($0, packageName: moduleName, groupName: group.name)
-            }
-
-            groups.append(groupSymbol)
-            snippets.append(contentsOf: snippetSymbols)
-
-            let snippetGroupRelationships = snippetSymbols.map { snippetSymbol in
-                SymbolGraph.Relationship(source: snippetSymbol.identifier.precise, target: groupSymbol.identifier.precise, kind: .memberOf, targetFallback: nil)
-            }
-            relationships.append(contentsOf: snippetGroupRelationships)
-        }
-
+    func emitSymbolGraph(for snippets: [Snippet], to emitFilename: URL, moduleName: String) throws {
+        let snippetSymbols = snippets.map { SymbolGraph.Symbol($0, moduleName: moduleName) }
         let metadata = SymbolGraph.Metadata(formatVersion: .init(major: 0, minor: 1, patch: 0), generator: "swift-docc-plugin/snippet-build")
         let module = SymbolGraph.Module(name: moduleName, platform: .init(architecture: nil, vendor: nil, operatingSystem: nil, environment: nil))
-        let symbolGraph = SymbolGraph(metadata: metadata, module: module, symbols: groups + snippets, relationships: relationships)
+        let symbolGraph = SymbolGraph(metadata: metadata, module: module, symbols: snippetSymbols, relationships: [])
         try FileManager.default.createDirectory(atPath: emitFilename.deletingLastPathComponent().path, withIntermediateDirectories: true, attributes: nil)
         let encoder = JSONEncoder()
         let data = try encoder.encode(symbolGraph)
@@ -95,44 +72,18 @@ struct SnippetBuildCommand {
             .filter { $0.isDirectory }
     }
 
-    func loadSnippetsAndSnippetGroups(from snippetsDirectory: URL) throws -> [SnippetGroup] {
+    func loadSnippets(from snippetsDirectory: URL) throws -> [Snippet] {
         guard snippetsDirectory.isDirectory else {
             return []
         }
 
-        let topLevelSnippets = try files(in: snippetsDirectory, withExtension: "swift")
-            .map { try Snippet(parsing: $0) }
-
-        let topLevelSnippetGroup = SnippetGroup(name: "Snippets",
-                                                baseDirectory: snippetsDirectory,
-                                                snippets: topLevelSnippets,
-                                                explanation: "")
-
-        let subdirectoryGroups = try subdirectories(in: snippetsDirectory)
-            .map { subdirectory -> SnippetGroup in
-                let snippets = try files(in: subdirectory, withExtension: "swift")
-                    .map { try Snippet(parsing: $0) }
-
-                let explanationFile = subdirectory.appendingPathComponent("Explanation.md")
-
-                let snippetGroupExplanation: String
-                if explanationFile.isFile {
-                    snippetGroupExplanation = try String(contentsOf: explanationFile)
-                } else {
-                    snippetGroupExplanation = ""
+        let snippetFiles = try files(in: snippetsDirectory, withExtension: "swift") +
+            subdirectories(in: snippetsDirectory)
+                .flatMap { subdirectory -> [URL] in
+                    try files(in: subdirectory, withExtension: "swift")
                 }
 
-                return SnippetGroup(name: subdirectory.lastPathComponent,
-                                    baseDirectory: subdirectory,
-                                    snippets: snippets,
-                                    explanation: snippetGroupExplanation)
-            }
-
-        let snippetGroups = [topLevelSnippetGroup] + subdirectoryGroups.sorted {
-            $0.name < $1.name
-        }
-
-        return snippetGroups.filter { !$0.snippets.isEmpty }
+        return try snippetFiles.map { try Snippet(parsing: $0) }
     }
 
     static func main() throws {

diff --git a/Sources/snippet-build/Utility/SymbolGraph+Snippet.swift b/Sources/snippet-build/Utility/SymbolGraph+Snippet.swift
@@ -10,30 +10,13 @@ import Snippets
 import struct SymbolKit.SymbolGraph
 
 extension SymbolGraph.Symbol {
-    /// Create a ``SymbolGraph.Symbol`` from a ``SnippetGroup``.
-    ///
-    /// - parameter packageName: The name to use for the package name in the snippet group symbol's precise identifier.
-    init(_ snippetGroup: Snippets.SnippetGroup, packageName: String) {
-        let identifier = SymbolGraph.Symbol.Identifier(precise: "$snippet__\(packageName).\(snippetGroup.name)", interfaceLanguage: "swift")
-        let names = SymbolGraph.Symbol.Names.init(title: snippetGroup.name, navigator: nil, subHeading: nil, prose: nil)
-        let pathComponents = [snippetGroup.name]
-        let docComment = SymbolGraph.LineList(snippetGroup.explanation
-                                    .split(separator: "\n", maxSplits: Int.max, omittingEmptySubsequences: false)
-                                    .map { line in
-            SymbolGraph.LineList.Line(text: String(line), range: nil)
-        })
-        let accessLevel = SymbolGraph.Symbol.AccessControl(rawValue: "public")
-        let kind = SymbolGraph.Symbol.Kind(parsedIdentifier: .snippetGroup, displayName: "Snippet Group")
-        self.init(identifier: identifier, names: names, pathComponents: pathComponents, docComment: docComment, accessLevel: accessLevel, kind: kind, mixins: [:])
-    }
-
     /// Create a ``SymbolGraph.Symbol`` from a ``Snippet``.
     ///
-    /// - parameter packageName: The name to use for the package name in the snippet symbol's precise identifier.
-    init(_ snippet: Snippets.Snippet, packageName: String, groupName: String) {
-        let identifier = SymbolGraph.Symbol.Identifier(precise: "$snippet__\(packageName).\(groupName).\(snippet.identifier)", interfaceLanguage: "swift")
+    /// - parameter moduleName: The name to use for the package name in the snippet symbol's precise identifier.
+    init(_ snippet: Snippets.Snippet, moduleName: String) {
+        let identifier = SymbolGraph.Symbol.Identifier(precise: "$snippet__\(moduleName).\(snippet.identifier)", interfaceLanguage: "swift")
         let names = SymbolGraph.Symbol.Names.init(title: snippet.identifier, navigator: nil, subHeading: nil, prose: nil)
-        let pathComponents = [packageName, groupName, snippet.identifier]
+        let pathComponents = ["snippets", snippet.identifier]
         let docComment = SymbolGraph.LineList(snippet.explanation
                                     .split(separator: "\n", maxSplits: Int.max, omittingEmptySubsequences: false)
                                     .map { line in

diff --git a/Tests/SwiftDocCPluginUtilitiesTests/SnippetBuildTests.swift b/Tests/SwiftDocCPluginUtilitiesTests/SnippetBuildTests.swift
@@ -19,7 +19,6 @@ class SnippetBuildTests: XCTestCase {
         XCTAssertEqual(fakeSourceFilename, snippet.sourceFile)
         XCTAssertTrue(snippet.explanation.isEmpty)
         XCTAssertTrue(snippet.presentationCode.isEmpty)
-        XCTAssertNil(snippet.groupName)
         XCTAssertEqual("test", snippet.identifier)
     }
 
@@ -53,7 +52,6 @@ class SnippetBuildTests: XCTestCase {
         XCTAssertEqual(fakeSourceFilename, snippet.sourceFile)
         XCTAssertEqual(expectedExplanation, snippet.explanation)
         XCTAssertEqual(expectedCode, snippet.presentationCode)
-        XCTAssertNil(snippet.groupName)
         XCTAssertEqual("test", snippet.identifier)
     }