Move configuration before context initialization

Sources/SwiftDocC/DocumentationService/Convert/ConvertService.swift

@@ -150,14 +150,15 @@ public struct ConvertService: DocumentationService {
                 provider = inMemoryProvider
             }
 
-            let context = try DocumentationContext(dataProvider: workspace)
-            context.knownDisambiguatedSymbolPathComponents = request.knownDisambiguatedSymbolPathComponents
+            var configuration = DocumentationContext.Configuration()
+
+            configuration.convertServiceConfiguration.knownDisambiguatedSymbolPathComponents = request.knownDisambiguatedSymbolPathComponents
 
             // Enable support for generating documentation for standalone articles and tutorials.
-            context.allowsRegisteringArticlesWithoutTechnologyRoot = true
-            context.considerDocumentationExtensionsThatDoNotMatchSymbolsAsResolved = true
+            configuration.convertServiceConfiguration.allowsRegisteringArticlesWithoutTechnologyRoot = true
+            configuration.convertServiceConfiguration.considerDocumentationExtensionsThatDoNotMatchSymbolsAsResolved = true
 
-            context.configureSymbolGraph = { symbolGraph in
+            configuration.convertServiceConfiguration.symbolGraphTransformer = { symbolGraph in
                 for (symbolIdentifier, overridingDocumentationComment) in request.overridingDocumentationComments ?? [:] {
                     symbolGraph.symbols[symbolIdentifier]?.docComment = SymbolGraph.LineList(
                         overridingDocumentationComment.map(SymbolGraph.LineList.Line.init(_:))
@@ -172,10 +173,12 @@ public struct ConvertService: DocumentationService {
                     convertRequestIdentifier: messageIdentifier
                 )
 
-                context.convertServiceFallbackResolver = resolver
-                context.globalExternalSymbolResolver = resolver
+                configuration.convertServiceConfiguration.fallbackResolver = resolver
+                configuration.externalDocumentationConfiguration.globalSymbolResolver = resolver
             }
-
+
+            let context = try DocumentationContext(dataProvider: workspace, configuration: configuration)
+
             var converter = try self.converter ?? DocumentationConverter(
                 documentationBundleURL: request.bundleLocation ?? URL(fileURLWithPath: "/"),
                 emitDigest: false,

Sources/SwiftDocC/Infrastructure/Context/Deprecated/DocumentationContext+Deprecated.swift

@@ -0,0 +1,36 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2024 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
+*/
+
+extension DocumentationContext {
+
+    @available(*, deprecated, renamed: "configuration.externalMetadata", message: "Use 'configuration.externalMetadata' instead. This deprecated API will be removed after Swift 6.2 is released.")
+    public var externalMetadata: ExternalMetadata {
+        get { configuration.externalMetadata }
+        set { configuration.externalMetadata = newValue }
+    }
+
+    @available(*, deprecated, renamed: "configuration.externalDocumentationConfiguration.sources", message: "Use 'configuration.externalDocumentationConfiguration.sources' instead. This deprecated API will be removed after Swift 6.2 is released.")
+    public var externalDocumentationSources: [BundleIdentifier: ExternalDocumentationSource] {
+        get { configuration.externalDocumentationConfiguration.sources }
+        set { configuration.externalDocumentationConfiguration.sources = newValue }
+    }
+
+    @available(*, deprecated, renamed: "configuration.externalDocumentationConfiguration.globalSymbolResolver", message: "Use 'configuration.externalDocumentationConfiguration.globalSymbolResolver' instead. This deprecated API will be removed after Swift 6.2 is released.")
+    public var globalExternalSymbolResolver: GlobalExternalSymbolResolver? {
+        get { configuration.externalDocumentationConfiguration.globalSymbolResolver }
+        set { configuration.externalDocumentationConfiguration.globalSymbolResolver = newValue }
+    }
+
+    @available(*, deprecated, renamed: "configuration.experimentalCoverageConfiguration.shouldStoreManuallyCuratedReferences", message: "Use 'configuration.experimentalCoverageConfiguration.shouldStoreManuallyCuratedReferences' instead. This deprecated API will be removed after Swift 6.2 is released.")
+    public var shouldStoreManuallyCuratedReferences: Bool {
+        get { configuration.experimentalCoverageConfiguration.shouldStoreManuallyCuratedReferences }
+        set { configuration.experimentalCoverageConfiguration.shouldStoreManuallyCuratedReferences = newValue }
+    }
+}

Sources/SwiftDocC/Infrastructure/Context/DocumentationContext+Configuration.swift

@@ -0,0 +1,98 @@
+/*
+ This source file is part of the Swift.org open source project
+
+ Copyright (c) 2024 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 SymbolKit
+
+extension DocumentationContext {
+    /// A collection of configuration to apply to a documentation context during initialization.
+    public struct Configuration {
+        // This type exists so that the context doesn't need to be modified in-between creation and registration of the data provider.
+        // It's a small step towards making the context fully immutable.
+
+        /// Creates a new default configuration.
+        public init() {}
+
+        // MARK: Convert Service configuration
+
+        /// Configuration specific to the ``ConvertService``.
+        var convertServiceConfiguration = ConvertServiceConfiguration()
+
+        /// A collection of configuration specific to the ``ConvertService``.
+        struct ConvertServiceConfiguration {
+            /// The mapping of external symbol identifiers to known disambiguated symbol path components.
+            ///
+            /// In situations where the local documentation context doesn't contain all of the current module's
+            /// symbols, for example when using a ``ConvertService`` with a partial symbol graph,
+            /// the documentation context is otherwise unable to accurately detect a collision for a given symbol and correctly
+            /// disambiguate its path components. This value can be used to inject already disambiguated symbol
+            /// path components into the documentation context.
+            var knownDisambiguatedSymbolPathComponents: [String: [String]]?
+
+            /// Controls whether bundle registration should allow registering articles when no technology root is defined.
+            ///
+            /// Set this property to `true` to enable registering documentation for standalone articles,
+            /// for example when using ``ConvertService``.
+            var allowsRegisteringArticlesWithoutTechnologyRoot = false
+
+            /// Controls whether documentation extension files are considered resolved even when they don't match a symbol.
+            ///
+            /// Set this property to `true` to always consider documentation extensions as "resolved", for example when using  ``ConvertService``.
+            ///
+            /// > Note:
+            /// > Setting this property tor `true` means taking over the responsibility to match documentation extension files to symbols
+            /// > diagnosing unmatched documentation extension files, and diagnostic symbols that match multiple documentation extension files.
+            var considerDocumentationExtensionsThatDoNotMatchSymbolsAsResolved = false
+
+            /// A resolver that attempts to resolve local references to content that wasn't included in the catalog or symbol input.
+            ///
+            /// > Warning:
+            /// > Setting a fallback reference resolver makes accesses to the context non-thread-safe.
+            /// > This is because the fallback resolver can run during both local link resolution and during rendering, which both happen concurrently for each page.
+            /// > In practice this shouldn't matter because the convert service only builds documentation for one page.
+            var fallbackResolver: ConvertServiceFallbackResolver?
+
+            /// A closure that modifies each symbol graph before the context registers the symbol graph's information.
+            var symbolGraphTransformer: ((inout SymbolGraph) -> ())? = nil
+        }
+
+        // MARK: External metadata
+
+        /// External metadata injected into the context, for example via command line arguments.
+        public var externalMetadata = ExternalMetadata()
+
+        // MARK: External documentation
+
+        /// Configuration related to external sources of documentation.
+        public var externalDocumentationConfiguration = ExternalDocumentationConfiguration()
+
+        /// A collection of configuration related to external sources of documentation.
+        public struct ExternalDocumentationConfiguration {
+            /// The lookup of external documentation sources by their bundle identifiers.
+            public var sources: [BundleIdentifier: ExternalDocumentationSource] = [:]
+            /// A type that resolves all symbols that are referenced in symbol graph files but can't be found in any of the locally available symbol graph files.
+            public var globalSymbolResolver: GlobalExternalSymbolResolver?
+            /// A list of URLs to documentation archives that the local documentation depends on.
+            @_spi(ExternalLinks) // This needs to be public SPI so that the ConvertAction can set it.
+            public var dependencyArchives: [URL] = []
+        }
+
+        // MARK: Experimental coverage
+
+        /// Configuration related to the experimental documentation coverage feature.
+        package var experimentalCoverageConfiguration = ExperimentalCoverageConfiguration()
+
+        /// A collection of configuration related to the experimental documentation coverage feature.
+        package struct ExperimentalCoverageConfiguration {
+            /// Controls whether the context stores the set of references that are manually curated.
+            package var shouldStoreManuallyCuratedReferences: Bool = false
+        }
+    }
+}