|
| 1 | +/* |
| 2 | + This source file is part of the Swift.org open source project |
| 3 | + |
| 4 | + Copyright (c) 2024 Apple Inc. and the Swift project authors |
| 5 | + Licensed under Apache License v2.0 with Runtime Library Exception |
| 6 | + |
| 7 | + See https://swift.org/LICENSE.txt for license information |
| 8 | + See https://swift.org/CONTRIBUTORS.txt for Swift project authors |
| 9 | +*/ |
| 10 | + |
| 11 | +import Foundation |
| 12 | +import SymbolKit |
| 13 | + |
| 14 | +extension DocumentationContext { |
| 15 | + /// A collection of configuration to apply to a documentation context during initialization. |
| 16 | + public struct Configuration { |
| 17 | + // This type exists so that the context doesn't need to be modified in-between creation and registration of the data provider. |
| 18 | + // It's a small step towards making the context fully immutable. |
| 19 | + |
| 20 | + /// Creates a new default configuration. |
| 21 | + public init() {} |
| 22 | + |
| 23 | + // MARK: Convert Service configuration |
| 24 | + |
| 25 | + /// Configuration specific to the ``ConvertService``. |
| 26 | + var convertServiceConfiguration = ConvertServiceConfiguration() |
| 27 | + |
| 28 | + /// A collection of configuration specific to the ``ConvertService``. |
| 29 | + struct ConvertServiceConfiguration { |
| 30 | + /// The mapping of external symbol identifiers to known disambiguated symbol path components. |
| 31 | + /// |
| 32 | + /// In situations where the local documentation context doesn't contain all of the current module's |
| 33 | + /// symbols, for example when using a ``ConvertService`` with a partial symbol graph, |
| 34 | + /// the documentation context is otherwise unable to accurately detect a collision for a given symbol and correctly |
| 35 | + /// disambiguate its path components. This value can be used to inject already disambiguated symbol |
| 36 | + /// path components into the documentation context. |
| 37 | + var knownDisambiguatedSymbolPathComponents: [String: [String]]? |
| 38 | + |
| 39 | + /// Controls whether bundle registration should allow registering articles when no technology root is defined. |
| 40 | + /// |
| 41 | + /// Set this property to `true` to enable registering documentation for standalone articles, |
| 42 | + /// for example when using ``ConvertService``. |
| 43 | + var allowsRegisteringArticlesWithoutTechnologyRoot = false |
| 44 | + |
| 45 | + /// Controls whether documentation extension files are considered resolved even when they don't match a symbol. |
| 46 | + /// |
| 47 | + /// Set this property to `true` to always consider documentation extensions as "resolved", for example when using ``ConvertService``. |
| 48 | + /// |
| 49 | + /// > Note: |
| 50 | + /// > Setting this property tor `true` means taking over the responsibility to match documentation extension files to symbols |
| 51 | + /// > diagnosing unmatched documentation extension files, and diagnostic symbols that match multiple documentation extension files. |
| 52 | + var considerDocumentationExtensionsThatDoNotMatchSymbolsAsResolved = false |
| 53 | + |
| 54 | + /// A resolver that attempts to resolve local references to content that wasn't included in the catalog or symbol input. |
| 55 | + /// |
| 56 | + /// > Warning: |
| 57 | + /// > Setting a fallback reference resolver makes accesses to the context non-thread-safe. |
| 58 | + /// > This is because the fallback resolver can run during both local link resolution and during rendering, which both happen concurrently for each page. |
| 59 | + /// > In practice this shouldn't matter because the convert service only builds documentation for one page. |
| 60 | + var fallbackResolver: ConvertServiceFallbackResolver? |
| 61 | + |
| 62 | + /// A closure that modifies each symbol graph before the context registers the symbol graph's information. |
| 63 | + var symbolGraphTransformer: ((inout SymbolGraph) -> ())? = nil |
| 64 | + } |
| 65 | + |
| 66 | + // MARK: External metadata |
| 67 | + |
| 68 | + /// External metadata injected into the context, for example via command line arguments. |
| 69 | + public var externalMetadata = ExternalMetadata() |
| 70 | + |
| 71 | + // MARK: External documentation |
| 72 | + |
| 73 | + /// Configuration related to external sources of documentation. |
| 74 | + public var externalDocumentationConfiguration = ExternalDocumentationConfiguration() |
| 75 | + |
| 76 | + /// A collection of configuration related to external sources of documentation. |
| 77 | + public struct ExternalDocumentationConfiguration { |
| 78 | + /// The lookup of external documentation sources by their bundle identifiers. |
| 79 | + public var sources: [BundleIdentifier: ExternalDocumentationSource] = [:] |
| 80 | + /// 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. |
| 81 | + public var globalSymbolResolver: GlobalExternalSymbolResolver? |
| 82 | + /// A list of URLs to documentation archives that the local documentation depends on. |
| 83 | + @_spi(ExternalLinks) // This needs to be public SPI so that the ConvertAction can set it. |
| 84 | + public var dependencyArchives: [URL] = [] |
| 85 | + } |
| 86 | + |
| 87 | + // MARK: Experimental coverage |
| 88 | + |
| 89 | + /// Configuration related to the experimental documentation coverage feature. |
| 90 | + package var experimentalCoverageConfiguration = ExperimentalCoverageConfiguration() |
| 91 | + |
| 92 | + /// A collection of configuration related to the experimental documentation coverage feature. |
| 93 | + package struct ExperimentalCoverageConfiguration { |
| 94 | + /// Controls whether the context stores the set of references that are manually curated. |
| 95 | + package var shouldStoreManuallyCuratedReferences: Bool = false |
| 96 | + } |
| 97 | + } |
| 98 | +} |
0 commit comments