Initial implementation of HTML support

Author: mattt

Package.resolved

@@ -9,16 +9,19 @@ let package = Package(
         .package(url: "https://github.com/apple/swift-syntax.git", .revision("swift-5.2-DEVELOPMENT-SNAPSHOT-2020-03-09-a")),
         .package(url: "https://github.com/SwiftDocOrg/SwiftSemantics.git", .branch("swift-5.2")),
         .package(url: "https://github.com/SwiftDocOrg/CommonMark.git", .branch("master")),
-        .package(url: "https://github.com/SwiftDocOrg/SwiftMarkup.git", .upToNextMinor(from: "0.0.4")),
-        .package(url: "https://github.com/SwiftDocOrg/GraphViz.git", .upToNextMinor(from: "0.0.1")),
-        .package(url: "https://github.com/apple/swift-argument-parser", .upToNextMinor(from: "0.0.2")),
+        .package(url: "https://github.com/SwiftDocOrg/SwiftMarkup.git", .upToNextMinor(from: "0.0.5")),
+        .package(url: "https://github.com/SwiftDocOrg/GraphViz.git", .revision("ce0327a62c4b5a5ddd4741406ea54f164f228a54")),
+        .package(url: "https://github.com/NSHipster/HypertextLiteral.git", .upToNextMinor(from: "0.0.2")),
+        .package(url: "https://github.com/SwiftDocOrg/Markup.git", .revision("bcc9bff98749f8ed92221375591a1afd61b02f1a")),
+        .package(url: "https://github.com/NSHipster/SwiftSyntaxHighlighter.git", .revision("fe39b4ec07e1e37872adf4b506d223ab27cf8cea")),
+        .package(url: "https://github.com/apple/swift-argument-parser.git", .upToNextMinor(from: "0.0.2")),
     ],
     targets: [
         // Targets are the basic building blocks of a package. A target can define a module or a test suite.
         // Targets can depend on other targets in this package, and on products in packages which this package depends on.
         .target(
             name: "swift-doc",
-            dependencies: ["ArgumentParser", "SwiftDoc", "SwiftSemantics", "SwiftMarkup", "CommonMarkBuilder", "DCOV", "GraphViz"]
+            dependencies: ["ArgumentParser", "SwiftDoc", "SwiftSemantics", "SwiftMarkup", "CommonMarkBuilder", "HypertextLiteral", "Markup", "DCOV", "GraphViz", "SwiftSyntaxHighlighter"]
         ),
         .target(
             name: "DCOV",

Package.swift

@@ -1,17 +1,21 @@
 import Dispatch
 
-extension Array {
+public extension RandomAccessCollection {
     func parallelMap<T>(_ transform: (Element) throws -> T) throws -> [T] {
         guard count > 1 else {
             return try map(transform)
         }
 
-        var results = [(index: Int, result: Result<T, Error>)]()
+        let indices = Array(self.indices)
+
+        var results = [(index: Index, result: Result<T, Error>)]()
         results.reserveCapacity(count)
 
-        let queue = DispatchQueue(label: "org.swiftdoc.swift-doc.parallelMap")
+        let queue = DispatchQueue(label: #function)
         withoutActuallyEscaping(transform) { escapingtransform in
-            DispatchQueue.concurrentPerform(iterations: count) { (index) in
+            DispatchQueue.concurrentPerform(iterations: count) { (iteration) in
+                let index = indices[iteration]
+
                 do {
                     let transformed = try escapingtransform(self[index])
                     queue.sync {
@@ -36,4 +40,8 @@ extension Array {
     func parallelFlatMap<T>(transform: (Element) throws -> [T]) throws -> [T] {
         return try parallelMap(transform).flatMap { $0 }
     }
+
+    func parallelForEach(_ body: (Element) throws -> Void) throws {
+        _ = try parallelMap(body)
+    }
 }

Sources/SwiftDoc/Extensions/Array+Parallel.swift

@@ -13,16 +13,20 @@ public final class Interface: Codable {
 
     // MARK: -
 
-    private lazy var symbolsByIdentifier: [Symbol.ID: [Symbol]] = {
+    public lazy var symbolsGroupedByIdentifier: [Symbol.ID: [Symbol]] = {
         return Dictionary(grouping: symbols, by: { $0.id })
     }()
 
+    public lazy var symbolsGroupedByName: [String: [Symbol]] = {
+        return Dictionary(grouping: symbols, by: { $0.name })
+    }()
+
     public private(set) lazy var topLevelSymbols: [Symbol] = {
-        return symbols.filter { $0.declaration is Type || $0.id.pathComponents.isEmpty }
+        return symbols.filter { $0.api is Type || $0.id.pathComponents.isEmpty }
     }()
 
     public private(set) lazy var baseClasses: [Symbol] = {
-        return symbols.filter { $0.declaration is Class &&
+        return symbols.filter { $0.api is Class &&
             typesInherited(by: $0).isEmpty }
     }()
 
@@ -42,6 +46,12 @@ public final class Interface: Codable {
         return classClusters
     }()
 
+    private lazy var extensionsByExtendedType: [String: [Extension]] = {
+        return Dictionary(grouping: symbols.flatMap { $0.context.compactMap { $0 as? Extension } }) {
+            $0.extendedType
+        }
+    }()
+
     public private(set) lazy var relationships: [Relationship] = {
         var relationships: Set<Relationship> = []
         for symbol in symbols {
@@ -50,9 +60,9 @@ public final class Interface: Codable {
             if let container = symbol.context.compactMap({ $0 as? Symbol }).last {
                 let predicate: Relationship.Predicate
 
-                switch container.declaration {
+                switch container.api {
                 case is Protocol:
-                    if symbol.declaration.modifiers.contains(where: { $0.name == "optional" }) {
+                    if symbol.api.modifiers.contains(where: { $0.name == "optional" }) {
                         predicate = .optionalRequirementOf
                     } else {
                         predicate = .requirementOf
@@ -65,9 +75,10 @@ public final class Interface: Codable {
             }
 
             if let `extension` = `extension` {
-                for extended in symbols.filter({ $0.declaration is Type &&  $0.id.matches(`extension`.extendedType) }) {
+                if let extended = symbols.first(where: { $0.api is Type &&  $0.id.matches(`extension`.extendedType) }) {
+
                     let predicate: Relationship.Predicate
-                    switch extended.declaration {
+                    switch extended.api {
                     case is Protocol:
                         predicate = .defaultImplementationOf
                     default:
@@ -78,17 +89,26 @@ public final class Interface: Codable {
                 }
             }
 
-            if let type = symbol.declaration as? Type {
-                let inheritance = Set((type.inheritance + (`extension`?.inheritance ?? [])).flatMap { $0.split(separator: "&").map { $0.trimmingCharacters(in: .whitespaces) } })
-                for name in inheritance {
-                    let inheritedTypes = symbols.filter({ ($0.declaration is Class || $0.declaration is Protocol) && $0.id.matches(name) })
+            if let type = symbol.api as? Type {
+                var inheritedTypeNames: Set<String> = []
+                inheritedTypeNames.formUnion(type.inheritance.flatMap { $0.split(separator: "&").map { $0.trimmingCharacters(in: .whitespaces) }
+                })
+
+                for `extension` in extensionsByExtendedType[symbol.id.description] ?? [] {
+                    inheritedTypeNames.formUnion(`extension`.inheritance)
+                }
+
+                inheritedTypeNames = Set(inheritedTypeNames.flatMap { $0.split(separator: "&").map { $0.trimmingCharacters(in: .whitespaces) } })
+
+                for name in inheritedTypeNames {
+                    let inheritedTypes = symbols.filter({ ($0.api is Class || $0.api is Protocol) && $0.id.matches(name) })
                     if inheritedTypes.isEmpty {
-                        let inherited = Symbol(declaration: Unknown(name: name), context: [], documentation: nil, sourceLocation: nil)
+                        let inherited = Symbol(api: Unknown(name: name), context: [], declaration: nil, documentation: nil, sourceLocation: nil)
                         relationships.insert(Relationship(subject: symbol, predicate: .inheritsFrom, object: inherited))
                     } else {
                         for inherited in inheritedTypes {
                             let predicate: Relationship.Predicate
-                            if symbol.declaration is Class, inherited.declaration is Class {
+                            if symbol.api is Class, inherited.api is Class {
                                 predicate = .inheritsFrom
                             } else {
                                 predicate = .conformsTo
@@ -104,26 +124,26 @@ public final class Interface: Codable {
         return Array(relationships)
     }()
 
-    private lazy var relationshipsBySubject: [Symbol.ID: [Relationship]] = {
+    public private(set) lazy var relationshipsBySubject: [Symbol.ID: [Relationship]] = {
         Dictionary(grouping: relationships, by: { $0.subject.id })
     }()
 
-    private lazy var relationshipsByObject: [Symbol.ID: [Relationship]] = {
+    public private(set) lazy var relationshipsByObject: [Symbol.ID: [Relationship]] = {
         Dictionary(grouping: relationships, by: { $0.object.id })
     }()
 
     // MARK: -
 
     public func members(of symbol: Symbol) -> [Symbol] {
-        return relationshipsByObject[symbol.id]?.filter { $0.predicate == .memberOf }.map { $0.subject } ?? []
+        return relationshipsByObject[symbol.id]?.filter { $0.predicate == .memberOf }.map { $0.subject }.sorted() ?? []
     }
 
     public func requirements(of symbol: Symbol) -> [Symbol] {
-        return relationshipsByObject[symbol.id]?.filter { $0.predicate == .requirementOf }.map { $0.subject } ?? []
+        return relationshipsByObject[symbol.id]?.filter { $0.predicate == .requirementOf }.map { $0.subject }.sorted() ?? []
     }
 
     public func optionalRequirements(of symbol: Symbol) -> [Symbol] {
-        return relationshipsByObject[symbol.id]?.filter { $0.predicate == .optionalRequirementOf }.map { $0.subject } ?? []
+        return relationshipsByObject[symbol.id]?.filter { $0.predicate == .optionalRequirementOf }.map { $0.subject }.sorted() ?? []
     }
 
     public func typesInherited(by symbol: Symbol) -> [Symbol] {
@@ -143,6 +163,6 @@ public final class Interface: Codable {
     }
 
     public func conditionalCounterparts(of symbol: Symbol) -> [Symbol] {
-        return symbolsByIdentifier[symbol.id]?.filter { $0 != symbol } ?? []
+        return symbolsGroupedByIdentifier[symbol.id]?.filter { $0 != symbol }.sorted() ?? []
     }
 }

Sources/SwiftDoc/Interface.swift

@@ -8,7 +8,9 @@ public final class Module: Codable {
     public let sourceFiles: [SourceFile]
 
     public lazy var interface: Interface = {
-        Interface(imports: sourceFiles.flatMap { $0.imports }, symbols: sourceFiles.flatMap { $0.symbols })
+        let imports = sourceFiles.flatMap { $0.imports }
+        let symbols = sourceFiles.flatMap { $0.symbols }
+        return Interface(imports: imports, symbols: symbols)
     }()
 
     public required init(name: String = "Anonymous", sourceFiles: [SourceFile]) {

Sources/SwiftDoc/Module.swift

@@ -35,9 +35,12 @@ public struct SourceFile: Hashable, Codable {
         var visitedSymbols: [Symbol] = []
         var visitedImports: [Import] = []
 
+        let fileURL: URL
         let sourceLocationConverter: SourceLocationConverter
 
         init(file url: URL, relativeTo directory: URL) throws {
+            self.fileURL = url
+
             let tree = try SyntaxParser.parse(url)
             sourceLocationConverter = SourceLocationConverter(file: url.path(relativeTo: directory), tree: tree)
             super.init()
@@ -48,21 +51,22 @@ public struct SourceFile: Hashable, Codable {
         }
 
         func symbol<Node, Declaration>(_ type: Declaration.Type, _ node: Node) -> Symbol? where Declaration: API & ExpressibleBySyntax, Node == Declaration.Syntax {
-            guard let declaration = Declaration(node) else { return nil }
-            return symbol(node, declaration: declaration)
+            guard let api = Declaration(node) else { return nil }
+            return symbol(node, api: api)
         }
 
-        func symbol<Node: SyntaxProtocol>(_ node: Node, declaration: API) -> Symbol? {
+        func symbol<Node: SyntaxProtocol>(_ node: Node, api: API) -> Symbol? {
             guard let documentation = try? Documentation.parse(node.documentation) else { return nil }
             let sourceLocation = sourceLocationConverter.location(for: node.position)
-            return Symbol(declaration: declaration, context: context, documentation: documentation, sourceLocation: sourceLocation)
+
+            return Symbol(api: api, context: context, declaration: "\(api)", documentation: documentation, sourceLocation: sourceLocation)
         }
 
         func push(_ symbol: Symbol?) {
             guard let symbol = symbol else { return }
             visitedSymbols.append(symbol)
 
-            switch symbol.declaration {
+            switch symbol.api {
             case is Class,
                  is Enumeration,
                  is Protocol,
@@ -108,7 +112,7 @@ public struct SourceFile: Hashable, Codable {
 
         override func visit(_ node: EnumCaseDeclSyntax) -> SyntaxVisitorContinueKind {
             for `case` in Enumeration.Case.cases(from: node) {
-                push(symbol(node, declaration: `case`))
+                push(symbol(node, api: `case`))
             }
             return .skipChildren
         }
@@ -175,19 +179,19 @@ public struct SourceFile: Hashable, Codable {
 
         override func visit(_ node: VariableDeclSyntax) -> SyntaxVisitorContinueKind {
             for variable in Variable.variables(from: node) {
-                push(symbol(node, declaration: variable))
+                push(symbol(node, api: variable))
             }
             return .skipChildren
         }
 
         // MARK: -
 
         override func visitPost(_ node: ClassDeclSyntax) {
-            assert((pop() as? Symbol)?.declaration is Class)
+            assert((pop() as? Symbol)?.api is Class)
         }
 
         override func visitPost(_ node: EnumDeclSyntax) {
-            assert((pop() as? Symbol)?.declaration is Enumeration)
+            assert((pop() as? Symbol)?.api is Enumeration)
         }
 
         override func visitPost(_ node: ExtensionDeclSyntax) {
@@ -199,11 +203,11 @@ public struct SourceFile: Hashable, Codable {
         }
 
         override func visitPost(_ node: ProtocolDeclSyntax) {
-            assert((pop() as? Symbol)?.declaration is Protocol)
+            assert((pop() as? Symbol)?.api is Protocol)
         }
 
         override func visitPost(_ node: StructDeclSyntax) {
-            assert((pop() as? Symbol)?.declaration is Structure)
+            assert((pop() as? Symbol)?.api is Structure)
         }
     }
 }