Rename "Technology" to "Tutorial Table of Contents" (#1039)

* Rename Technology to match user-facing TutorialTableOfContents term

* Update usage of the renamed technology type

* Update other API that use the Technology name

* Rename technology case for URL creation

* Rename technology documentation node kind

* Rename bundle's technology reference properties

* Update directive symbol graph file

* Update additional uses of technology in tests

* Rename `preferTechnologysRoot` to `preferTutorialTableOfContentsRoot

* Add comments to deprecations to indicate when they can be removed

* Update link in contributor documentation

* Update additional variables and code comments

* Add back deprecated fallbackOverview cases in switch statements

* Add "Results" suffix to TOC semantic results lists to avoid `for A in A {}` pattern

Author: d-ronnqvist

Sources/SwiftDocC/Infrastructure/DocumentationBundle.swift

@@ -128,8 +128,8 @@ public struct DocumentationBundle {
         self.themeSettings = themeSettings
         self.rootReference = ResolvedTopicReference(bundleIdentifier: info.identifier, path: "/", sourceLanguage: .swift)
         self.documentationRootReference = ResolvedTopicReference(bundleIdentifier: info.identifier, path: NodeURLGenerator.Path.documentationFolder, sourceLanguage: .swift)
-        self.tutorialsRootReference = ResolvedTopicReference(bundleIdentifier: info.identifier, path: NodeURLGenerator.Path.tutorialsFolder, sourceLanguage: .swift)
-        self.technologyTutorialsRootReference = tutorialsRootReference.appendingPath(urlReadablePath(info.displayName))
+        self.tutorialTableOfContentsContainer = ResolvedTopicReference(bundleIdentifier: info.identifier, path: NodeURLGenerator.Path.tutorialsFolder, sourceLanguage: .swift)
+        self.tutorialsContainerReference = tutorialTableOfContentsContainer.appendingPath(urlReadablePath(info.displayName))
         self.articlesDocumentationRootReference = documentationRootReference.appendingPath(urlReadablePath(info.displayName))
     }
 
@@ -154,12 +154,22 @@ public struct DocumentationBundle {
     /// Default path to resolve symbol links.
     public private(set) var documentationRootReference: ResolvedTopicReference
 
-    /// Default path to resolve technology links.
-    public var tutorialsRootReference: ResolvedTopicReference
+    @available(*, deprecated, renamed: "tutorialTableOfContentsContainer", message: "Use 'tutorialTableOfContentsContainer' instead. This deprecated API will be removed after 6.2 is released")
+    public var tutorialsRootReference: ResolvedTopicReference {
+        tutorialTableOfContentsContainer
+    }
+
+    /// Default path to resolve tutorial table-of-contents links.
+    public var tutorialTableOfContentsContainer: ResolvedTopicReference
+
+    @available(*, deprecated, renamed: "tutorialsContainerReference", message: "Use 'tutorialsContainerReference' instead. This deprecated API will be removed after 6.2 is released")
+    public var technologyTutorialsRootReference: ResolvedTopicReference {
+        tutorialsContainerReference
+    }
+
+    /// Default path to resolve tutorial links.
+    public var tutorialsContainerReference: ResolvedTopicReference
 
-    /// Default path to resolve tutorials.
-    public var technologyTutorialsRootReference: ResolvedTopicReference
-    
     /// Default path to resolve articles.
     public var articlesDocumentationRootReference: ResolvedTopicReference
 }

Sources/SwiftDocC/Infrastructure/DocumentationContext+Breadcrumbs.swift

@@ -13,8 +13,8 @@ extension DocumentationContext {
     struct PathOptions: OptionSet {
         let rawValue: Int
 
-        /// Prefer a technology as the canonical path over a shorter path.
-        static let preferTechnologyRoot = PathOptions(rawValue: 1 << 0)
+        /// Prefer a tutorial table-of-contents page as the canonical path over a shorter path.
+        static let preferTutorialTableOfContentsRoot = PathOptions(rawValue: 1 << 0)
     }
 
     /// Finds all finite (acyclic) paths, also called "breadcrumbs", to the given reference in the topic graph.
@@ -38,9 +38,9 @@ extension DocumentationContext {
             // To match the caller's expectations we remove the starting point and then flip the paths.
             .map { $0.dropFirst().reversed() }
             .sorted { (lhs, rhs) -> Bool in
-                // Order a path rooted in a technology as the canonical one.
-                if options.contains(.preferTechnologyRoot), let first = lhs.first {
-                    return try! entity(with: first).semantic is Technology
+                // Order a path rooted in a tutorial table-of-contents as the canonical one.
+                if options.contains(.preferTutorialTableOfContentsRoot), let first = lhs.first {
+                    return try! entity(with: first).semantic is TutorialTableOfContents
                 }
 
                 return breadcrumbsAreInIncreasingOrder(lhs, rhs)

Sources/SwiftDocC/Infrastructure/DocumentationContext.swift

@@ -136,10 +136,15 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
     /// The set of all manually curated references if `shouldStoreManuallyCuratedReferences` was true at the time of processing and has remained `true` since.. Nil if curation has not been processed yet.
     public private(set) var manuallyCuratedReferences: Set<ResolvedTopicReference>?
 
-    /// The root technology nodes of the Topic Graph.
+    @available(*, deprecated, renamed: "tutorialTableOfContentsReferences", message: "Use 'tutorialTableOfContentsReferences' This deprecated API will be removed after 6.2 is released")
     public var rootTechnologies: [ResolvedTopicReference] {
+        tutorialTableOfContentsReferences
+    }
+
+    /// The tutorial table-of-contents nodes in the topic graph.
+    public var tutorialTableOfContentsReferences: [ResolvedTopicReference] {
         return topicGraph.nodes.values.compactMap { node in
-            guard node.kind == .technology && parents(of: node.reference).isEmpty else {
+            guard node.kind == .tutorialTableOfContents && parents(of: node.reference).isEmpty else {
                 return nil
             }
             return node.reference
@@ -606,65 +611,65 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
     /// up in the context, not from the arrays that was passed as arguments.
     ///
     /// - Parameters:
-    ///   - technologies: The list of temporary 'technology' pages.
+    ///   - tutorialTableOfContentsResults: The list of temporary 'tutorial table-of-contents' pages.
     ///   - tutorials: The list of temporary 'tutorial' pages.
     ///   - tutorialArticles: The list of temporary 'tutorialArticle' pages.
     ///   - bundle: The bundle to resolve links against.
-    private func resolveLinks(technologies: [SemanticResult<Technology>],
-                              tutorials: [SemanticResult<Tutorial>],
-                              tutorialArticles: [SemanticResult<TutorialArticle>],
-                              bundle: DocumentationBundle) {
-        
+    private func resolveLinks(
+        tutorialTableOfContents tutorialTableOfContentsResults: [SemanticResult<TutorialTableOfContents>],
+        tutorials: [SemanticResult<Tutorial>],
+        tutorialArticles: [SemanticResult<TutorialArticle>],
+        bundle: DocumentationBundle
+    ) {
         let sourceLanguages = soleRootModuleReference.map { self.sourceLanguages(for: $0) } ?? [.swift]
 
-        // Technologies
-        
-        for technologyResult in technologies {
+        // Tutorial table-of-contents
+
+        for tableOfContentsResult in tutorialTableOfContentsResults {
             autoreleasepool {
-                let url = technologyResult.source
-                let unresolvedTechnology = technologyResult.value
+                let url = tableOfContentsResult.source
                 var resolver = ReferenceResolver(context: self, bundle: bundle)
-                let technology = resolver.visit(unresolvedTechnology) as! Technology
+                let tableOfContents = resolver.visit(tableOfContentsResult.value) as! TutorialTableOfContents
                 diagnosticEngine.emit(resolver.problems)
 
                 // Add to document map
-                documentLocationMap[url] = technologyResult.topicGraphNode.reference
-                
-                let technologyReference = technologyResult.topicGraphNode.reference.withSourceLanguages(sourceLanguages)
+                documentLocationMap[url] = tableOfContentsResult.topicGraphNode.reference
 
-                let technologyNode = DocumentationNode(
-                    reference: technologyReference,
-                    kind: .technology,
+                let tableOfContentsReference = tableOfContentsResult.topicGraphNode.reference.withSourceLanguages(sourceLanguages)
+
+                let tutorialTableOfContentsNode = DocumentationNode(
+                    reference: tableOfContentsReference,
+                    kind: .tutorialTableOfContents,
                     sourceLanguage: Self.defaultLanguage(in: sourceLanguages),
                     availableSourceLanguages: sourceLanguages,
-                    name: .conceptual(title: technology.intro.title),
-                    markup: technology.originalMarkup,
-                    semantic: technology
+                    name: .conceptual(title: tableOfContents.intro.title),
+                    markup: tableOfContents.originalMarkup,
+                    semantic: tableOfContents
                 )
-                documentationCache[technologyReference] = technologyNode
+                documentationCache[tableOfContentsReference] = tutorialTableOfContentsNode
 
-                // Update the reference in the topic graph with the technology's available languages.
+                // Update the reference in the topic graph with the table-of-contents page's available languages.
                 topicGraph.updateReference(
-                    technologyResult.topicGraphNode.reference,
-                    newReference: technologyReference
+                    tableOfContentsResult.topicGraphNode.reference,
+                    newReference: tableOfContentsReference
                 )
 
                 let anonymousVolumeName = "$volume"
 
-                for volume in technology.volumes {
+                for volume in tableOfContents.volumes {
                     // Graph node: Volume
-                    let volumeReference = technologyNode.reference.appendingPath(volume.name ?? anonymousVolumeName)
+                    let volumeReference = tutorialTableOfContentsNode.reference.appendingPath(volume.name ?? anonymousVolumeName)
                     let volumeNode = TopicGraph.Node(reference: volumeReference, kind: .volume, source: .file(url: url), title: volume.name ?? anonymousVolumeName)
                     topicGraph.addNode(volumeNode)
 
-                    // Graph edge: Technology -> Volume
-                    topicGraph.addEdge(from: technologyResult.topicGraphNode, to: volumeNode)
+                    // Graph edge: Tutorial table-of-contents -> Volume
+                    topicGraph.addEdge(from: tableOfContentsResult.topicGraphNode, to: volumeNode)
 
                     for chapter in volume.chapters {
                         // Graph node: Module
                         let baseNodeReference: ResolvedTopicReference
                         if volume.name == nil {
-                            baseNodeReference = technologyNode.reference
+                            baseNodeReference = tutorialTableOfContentsNode.reference
                         } else {
                             baseNodeReference = volumeNode.reference
                         }
@@ -761,15 +766,15 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
     }
 
     private func registerDocuments(from bundle: DocumentationBundle) throws -> (
-        technologies: [SemanticResult<Technology>],
+        tutorialTableOfContentsResults: [SemanticResult<TutorialTableOfContents>],
         tutorials: [SemanticResult<Tutorial>],
         tutorialArticles: [SemanticResult<TutorialArticle>],
         articles: [SemanticResult<Article>],
         documentationExtensions: [SemanticResult<Article>]
     ) {
         // First, try to understand the basic structure of the document by
         // analyzing it and putting references in as "unresolved".
-        var technologies = [SemanticResult<Technology>]()
+        var tutorialTableOfContentsResults = [SemanticResult<TutorialTableOfContents>]()
         var tutorials = [SemanticResult<Tutorial>]()
         var tutorialArticles = [SemanticResult<TutorialArticle>]()
         var articles = [SemanticResult<Article>]()
@@ -857,11 +862,11 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
              Add all topic graph nodes up front before resolution starts, because
              there may be circular linking.
              */
-            if let technology = analyzed as? Technology {
-                let topicGraphNode = TopicGraph.Node(reference: reference, kind: .technology, source: .file(url: url), title: technology.intro.title)
+            if let tableOfContents = analyzed as? TutorialTableOfContents {
+                let topicGraphNode = TopicGraph.Node(reference: reference, kind: .tutorialTableOfContents, source: .file(url: url), title: tableOfContents.intro.title)
                 topicGraph.addNode(topicGraphNode)
-                let result = SemanticResult(value: technology, source: url, topicGraphNode: topicGraphNode)
-                technologies.append(result)
+                let result = SemanticResult(value: tableOfContents, source: url, topicGraphNode: topicGraphNode)
+                tutorialTableOfContentsResults.append(result)
             } else if let tutorial = analyzed as? Tutorial {
                 let topicGraphNode = TopicGraph.Node(reference: reference, kind: .tutorial, source: .file(url: url), title: tutorial.title ?? "")
                 topicGraph.addNode(topicGraphNode)
@@ -920,7 +925,7 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
             }
         }
 
-        return (technologies, tutorials, tutorialArticles, articles, documentationExtensions)
+        return (tutorialTableOfContentsResults, tutorials, tutorialArticles, articles, documentationExtensions)
     }
 
     private func insertLandmarks(_ landmarks: some Sequence<Landmark>, from topicGraphNode: TopicGraph.Node, source url: URL) {
@@ -2098,7 +2103,7 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
         //       symbols or attempt to resolve links/references since the topic graph may not contain all documents
         //       or all symbols yet.
         var result: (
-            technologies: [SemanticResult<Technology>],
+            tutorialTableOfContentsResults: [SemanticResult<TutorialTableOfContents>],
             tutorials: [SemanticResult<Tutorial>],
             tutorialArticles: [SemanticResult<TutorialArticle>],
             articles: [SemanticResult<Article>],
@@ -2137,7 +2142,7 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
         }
 
         // All discovery went well, process the inputs.
-        let (technologies, tutorials, tutorialArticles, allArticles, documentationExtensions) = result
+        let (tutorialTableOfContentsResults, tutorials, tutorialArticles, allArticles, documentationExtensions) = result
         var (otherArticles, rootPageArticles) = splitArticles(allArticles)
 
         let globalOptions = (allArticles + documentationExtensions).compactMap { article in
@@ -2185,8 +2190,8 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
         for article in tutorialArticles {
             hierarchyBasedResolver.addTutorialArticle(article)
         }
-        for technology in technologies {
-            hierarchyBasedResolver.addTechnology(technology)
+        for tutorialTableOfContents in tutorialTableOfContentsResults {
+            hierarchyBasedResolver.addTutorialTableOfContents(tutorialTableOfContents)
         }
 
         registerRootPages(from: rootPageArticles, in: bundle)
@@ -2221,13 +2226,13 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
 
         // Third, any processing that relies on resolving other content is done, mainly resolving links.
         preResolveExternalLinks(semanticObjects:
-            technologies.map(referencedSemanticObject) +
+            tutorialTableOfContentsResults.map(referencedSemanticObject) +
             tutorials.map(referencedSemanticObject) +
             tutorialArticles.map(referencedSemanticObject),
             localBundleID: bundle.identifier)
 
         resolveLinks(
-            technologies: technologies,
+            tutorialTableOfContents: tutorialTableOfContentsResults,
             tutorials: tutorials,
             tutorialArticles: tutorialArticles,
             bundle: bundle
@@ -2913,8 +2918,8 @@ public class DocumentationContext: DocumentationContextDataProviderDelegate {
 extension DocumentationContext {
 
     /// The nodes that are allowed to be roots in the topic graph.
-    static var allowedRootNodeKinds: [DocumentationNode.Kind] = [.technology, .module]
-    
+    static var allowedRootNodeKinds: [DocumentationNode.Kind] = [.tutorialTableOfContents, .module]
+
     func analyzeTopicGraph() {
         // Find all nodes that are loose in the graph and have no parent but aren't supposed to
         let unexpectedRoots = topicGraph.nodes.values.filter { node in

Sources/SwiftDocC/Infrastructure/Link Resolution/LinkResolver.swift

@@ -193,9 +193,9 @@ private final class FallbackResolverBasedLinkResolver {
                 // First look up articles path
                 currentBundle.articlesDocumentationRootReference.url.appendingPathComponent(unresolvedReference.path),
                 // Then technology tutorials root path (for individual tutorial pages)
-                currentBundle.technologyTutorialsRootReference.url.appendingPathComponent(unresolvedReference.path),
+                currentBundle.tutorialsContainerReference.url.appendingPathComponent(unresolvedReference.path),
                 // Then tutorials root path (for tutorial table of contents pages)
-                currentBundle.tutorialsRootReference.url.appendingPathComponent(unresolvedReference.path),
+                currentBundle.tutorialTableOfContentsContainer.url.appendingPathComponent(unresolvedReference.path),
             ])
         }
         // Try resolving in the local context (as child)

Sources/SwiftDocC/Infrastructure/Link Resolution/PathHierarchy.swift

@@ -419,7 +419,7 @@ struct PathHierarchy {
     /// - Parameter name: The path component name of the tutorial overview (the file name without the file extension).
     /// - Returns: The new unique identifier that represent this tutorial overview.
     mutating func addTutorialOverview(name: String) -> ResolvedIdentifier {
-        return addNonSymbolChild(parent: tutorialOverviewContainer.identifier, name: name, kind: "technology")
+        return addNonSymbolChild(parent: tutorialOverviewContainer.identifier, name: name, kind: "tutorial-toc")
     }
 
     /// Adds a non-symbol child element to an existing element in the path hierarchy.