File: DocumentationContextConverter.swift

package info (click to toggle)
swiftlang 6.0.3-2
  • links: PTS, VCS
  • area: main
  • in suites: forky, sid, trixie
  • size: 2,519,992 kB
  • sloc: cpp: 9,107,863; ansic: 2,040,022; asm: 1,135,751; python: 296,500; objc: 82,456; f90: 60,502; lisp: 34,951; pascal: 19,946; sh: 18,133; perl: 7,482; ml: 4,937; javascript: 4,117; makefile: 3,840; awk: 3,535; xml: 914; fortran: 619; cs: 573; ruby: 573
file content (106 lines) | stat: -rw-r--r-- 5,391 bytes parent folder | download
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
    }
}