1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106
|
/*
This source file is part of the Swift.org open source project
Copyright (c) 2021-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
/// A converter from documentation nodes to render nodes.
///
/// As this type makes use of a `RenderContext` to look up commonly used pieces of content,
/// use this type when you are converting nodes in bulk.
///
/// If you are converting nodes ad-hoc use ``DocumentationNodeConverter`` instead.
public class DocumentationContextConverter {
/// The context the converter uses to resolve references it finds in the documentation node's content.
let context: DocumentationContext
/// The bundle that contains the content from which the documentation node originated.
let bundle: DocumentationBundle
/// A context that contains common pre-rendered pieces of content.
let renderContext: RenderContext
/// Whether the documentation converter should include source file
/// location metadata in any render nodes representing symbols it creates.
///
/// Before setting this value to `true` please confirm that your use case doesn't include
/// public distribution of any created render nodes as there are filesystem privacy and security
/// concerns with distributing this data.
let shouldEmitSymbolSourceFileURIs: Bool
/// Whether the documentation converter should include access level information for symbols.
let shouldEmitSymbolAccessLevels: Bool
/// A list of symbol IDs that have version of their documentation page with more content that a renderer can link to.
let symbolIdentifiersWithExpandedDocumentation: [String]?
/// The remote source control repository where the documented module's source is hosted.
let sourceRepository: SourceRepository?
/// Creates a new node converter for the given bundle and context.
///
/// The converter uses bundle and context to resolve references to other documentation and describe the documentation hierarchy.
///
/// - Parameters:
/// - bundle: The bundle that contains the content from which the documentation node originated.
/// - context: The context that the converter uses to to resolve references it finds in the documentation node's content.
/// - renderContext: A context that contains common pre-rendered pieces of content.
/// - emitSymbolSourceFileURIs: Whether the documentation converter should include
/// source file location metadata in any render nodes representing symbols it creates.
///
/// Before passing `true` please confirm that your use case doesn't include public
/// distribution of any created render nodes as there are filesystem privacy and security
/// concerns with distributing this data.
/// - emitSymbolAccessLevels: Whether the documentation converter should include access level information for symbols.
/// - sourceRepository: The source repository where the documentation's sources are hosted.
/// - symbolIdentifiersWithExpandedDocumentation: A list of symbol IDs that have version of their documentation page with more content that a renderer can link to.
public init(
bundle: DocumentationBundle,
context: DocumentationContext,
renderContext: RenderContext,
emitSymbolSourceFileURIs: Bool = false,
emitSymbolAccessLevels: Bool = false,
sourceRepository: SourceRepository? = nil,
symbolIdentifiersWithExpandedDocumentation: [String]? = nil
) {
self.bundle = bundle
self.context = context
self.renderContext = renderContext
self.shouldEmitSymbolSourceFileURIs = emitSymbolSourceFileURIs
self.shouldEmitSymbolAccessLevels = emitSymbolAccessLevels
self.sourceRepository = sourceRepository
self.symbolIdentifiersWithExpandedDocumentation = symbolIdentifiersWithExpandedDocumentation
}
/// Converts a documentation node to a render node.
///
/// Convert a documentation node into a render node to get a self-contained, persist-able representation of a given topic's data, so you can write it to disk, send it over a network, or otherwise process it.
/// - Parameters:
/// - node: The documentation node to convert.
/// - source: The source file for the documentation node.
/// - Returns: The render node representation of the documentation node.
public func renderNode(for node: DocumentationNode, at source: URL?) throws -> RenderNode? {
guard !node.isVirtual else {
return nil
}
var translator = RenderNodeTranslator(
context: context,
bundle: bundle,
identifier: node.reference,
source: source,
renderContext: renderContext,
emitSymbolSourceFileURIs: shouldEmitSymbolSourceFileURIs,
emitSymbolAccessLevels: shouldEmitSymbolAccessLevels,
sourceRepository: sourceRepository,
symbolIdentifiersWithExpandedDocumentation: symbolIdentifiersWithExpandedDocumentation
)
return translator.visit(node.semantic) as? RenderNode
}
}
|