Merge pull request #97 from SwiftDocOrg/commonmark-home-abstract

Include symbol summaries on Home page in CommonMark format

Author: mattt

Package.resolved

@@ -12,8 +12,8 @@ let package = Package(
     dependencies: [
         .package(url: "https://github.com/apple/swift-syntax.git", .revision("0.50200.0")),
         .package(url: "https://github.com/SwiftDocOrg/SwiftSemantics.git", .upToNextMinor(from: "0.1.0")),
-        .package(url: "https://github.com/SwiftDocOrg/CommonMark.git", .branch("master")),
-        .package(url: "https://github.com/SwiftDocOrg/SwiftMarkup.git", .upToNextMinor(from: "0.0.5")),
+        .package(url: "https://github.com/SwiftDocOrg/CommonMark.git", .revision("902cc82abc2e8ad23b73c982eed27c63ae3d9384")),
+        .package(url: "https://github.com/SwiftDocOrg/SwiftMarkup.git", .revision("0.2.0")),
         .package(url: "https://github.com/SwiftDocOrg/GraphViz.git", .revision("03405c13dc1c31f50c08bbec6e7587cbee1c7fb3")),
         .package(url: "https://github.com/NSHipster/HypertextLiteral.git", .upToNextMinor(from: "0.0.2")),
         .package(url: "https://github.com/SwiftDocOrg/Markup.git", .upToNextMinor(from: "0.0.3")),

Package.swift

@@ -0,0 +1,55 @@
+import CommonMarkBuilder
+import SwiftDoc
+import SwiftMarkup
+import SwiftSemantics
+import HypertextLiteral
+
+struct Abstract: Component {
+    var symbol: Symbol
+
+    init(for symbol: Symbol) {
+        self.symbol = symbol
+    }
+    
+    // MARK: - Component
+
+    var fragment: Fragment {
+        if let summary = symbol.documentation?.summary {
+            return Fragment {
+                List.Item {
+                    Paragraph {
+                        Link(urlString: path(for: symbol), text: symbol.id.description)
+                        Text { ":" }
+                    }
+
+                    Fragment {
+                        summary
+                    }
+                }
+            }
+        } else {
+            return Fragment {
+                List.Item {
+                    Paragraph {
+                        Link(urlString: path(for: symbol), text: symbol.id.description)
+                    }
+                }
+            }
+        }
+    }
+
+    var html: HypertextLiteral.HTML {
+        let descriptor = String(describing: type(of: symbol.api)).lowercased()
+
+        return #"""
+        <dt class="\#(descriptor)">
+            <a href=\#(path(for: symbol)) title="\#(descriptor) - \#(symbol.id.description)">
+                \#(softbreak(symbol.id.description))
+            </a>
+        </dt>
+        <dd>
+            \#(commonmark: symbol.documentation?.summary ?? "")
+        </dd>
+        """#
+    }
+}

Sources/swift-doc/Supporting Types/Components/Abstract.swift

@@ -40,11 +40,7 @@ struct Documentation: Component {
             Declaration(of: symbol, in: module)
 
             ForEach(in: documentation.discussionParts) { part in
-                if part is SwiftMarkup.Documentation.Callout {
-                    Callout(part as! SwiftMarkup.Documentation.Callout)
-                } else {
-                    Fragment { "\(part)" }
-                }
+                DiscussionPart(part, for: symbol, in: module)
             }
 
             if !documentation.parameters.isEmpty {
@@ -100,27 +96,8 @@ struct Documentation: Component {
         if !documentation.discussionParts.isEmpty {
             fragments.append(#"""
             <div class="discussion">
-                \#(documentation.discussionParts.compactMap { part -> HypertextLiteral.HTML? in
-                    if let part = part as? SwiftMarkup.Documentation.Callout {
-                        return Callout(part).html
-                    } else if let part = part as? String {
-                        if part.starts(with: "```"),
-                            let codeBlock = (try? CommonMark.Document(part))?.children.compactMap({ $0 as? CodeBlock }).first,
-                            (codeBlock.fenceInfo ?? "") == "" ||
-                                codeBlock.fenceInfo?.compare("swift", options: .caseInsensitive) == .orderedSame,
-                            let source = codeBlock.literal
-                        {
-                            var html = try! SwiftSyntaxHighlighter.highlight(source: source, using: Xcode.self)
-                            html = linkCodeElements(of: html, for: symbol, in: module)
-                            return HTML(html)
-                        } else {
-                            var html = (try! CommonMark.Document(part)).render(format: .html, options: [.unsafe])
-                            html = linkCodeElements(of: html, for: symbol, in: module)
-                            return HTML(html)
-                        }
-                    } else {
-                        return nil
-                    }
+                \#(documentation.discussionParts.compactMap { part -> HTML? in
+                    DiscussionPart(part, for: symbol, in: module).html
                 })
             </div>
             """# as HypertextLiteral.HTML)
@@ -197,29 +174,86 @@ struct Documentation: Component {
 }
 
 extension Documentation {
-    struct Callout: Component {
-        var callout: SwiftMarkup.Documentation.Callout
-
-        init(_ callout: SwiftMarkup.Documentation.Callout) {
-            self.callout = callout
+    struct DiscussionPart: Component {
+        var symbol: Symbol
+        var module: Module
+        var part: SwiftMarkup.DiscussionPart
+
+        init(_ part: SwiftMarkup.DiscussionPart, for symbol: Symbol, in module: Module) {
+            self.part = part
+            self.symbol = symbol
+            self.module = module
         }
 
         // MARK: - Component
 
         var fragment: Fragment {
-            Fragment {
-                """
-                > \(callout.delimiter.rawValue.capitalized): \(callout.content)
-                """
+            switch part {
+            case .blockQuote(let blockquote):
+                return Fragment {
+                    blockquote.render(format: .commonmark)
+                }
+            case .callout(let callout):
+                return Fragment {
+                    BlockQuote {
+                        "\(callout.delimiter.rawValue.capitalized): \(callout.content)"
+                    }
+                }
+            case .codeBlock(let codeBlock):
+                return Fragment {
+                    codeBlock.render(format: .commonmark)
+                }
+            case .heading(let heading):
+                return Fragment {
+                    heading.render(format: .commonmark)
+                }
+            case .htmlBlock(let htmlBlock):
+                return Fragment {
+                    htmlBlock.literal ?? ""
+                }
+            case .list(let list):
+                return Fragment {
+                    list.render(format: .commonmark)
+                }
+            case .paragraph(let paragraph):
+                return Fragment {
+                    paragraph.render(format: .commonmark)
+                }
             }
         }
 
         var html: HypertextLiteral.HTML {
-            return #"""
-            <aside class=\#(callout.delimiter.rawValue)>
-                \#(commonmark: callout.content)
-            </aside>
-            """#
+            switch part {
+            case .blockQuote(let blockquote):
+                return HTML(blockquote.render(format: .html, options: [.unsafe]))
+            case .callout(let callout):
+                return #"""
+                <aside class=\#(callout.delimiter.rawValue)>
+                    \#(commonmark: callout.content)
+                </aside>
+                """# as HTML
+            case .codeBlock(let codeBlock):
+                if (codeBlock.fenceInfo ?? "") == "" ||
+                        codeBlock.fenceInfo?.compare("swift", options: .caseInsensitive) == .orderedSame,
+                    let source = codeBlock.literal
+                {
+                    var html = try! SwiftSyntaxHighlighter.highlight(source: source, using: Xcode.self)
+                    html = linkCodeElements(of: html, for: symbol, in: module)
+                    return HTML(html)
+                } else {
+                    var html = codeBlock.render(format: .html, options: [.unsafe])
+                    html = linkCodeElements(of: html, for: symbol, in: module)
+                    return HTML(html)
+                }
+            case .heading(let heading):
+                return HTML(heading.render(format: .html, options: [.unsafe]))
+            case .htmlBlock(let htmlBlock):
+                return HTML(htmlBlock.literal ?? "")
+            case .list(let list):
+                return HTML(list.render(format: .html, options: [.unsafe]))
+            case .paragraph(let paragraph):
+                return HTML(paragraph.render(format: .html, options: [.unsafe]))
+            }
         }
     }
 }