improve styling of terms lists, and add more tests for doclink resolution

tayloraswift · tayloraswift · commit 9f3854891e43 · 2024-02-23T02:51:04.000Z
diff --git a/Assets/css/Main.css b/Assets/css/Main.css
diff --git a/Assets/css/Main.css.map b/Assets/css/Main.css.map
diff --git a/Sources/MarkdownParsing/Shims/Markdown.InlineElement (ext).swift b/Sources/MarkdownParsing/Shims/Markdown.InlineElement (ext).swift
@@ -62,14 +62,12 @@ extension Markdown.InlineElement:ParsableAsInlineMarkup
                 Markdown.InlineSpan.init(from: $0, in: source)
             }
             if  let destination:String = link.destination,
-                let colon:String.Index = destination.firstIndex(of: ":"),
-                    destination[..<colon] == "doc",
                     elements.count == 1,
                     elements[0] == .text(destination)
             {
                 // exclude the angle brackets from the source range
                 let link:Markdown.InlineAutolink = .doc(
-                    link: String.init(destination[destination.index(after: colon)...]),
+                    link: destination,
                     at: .init(trimming: 1, from: link.range, in: copy source))
 
                 self = .autolink(link)
diff --git a/Sources/SwiftinitPages/Surfaces/Vertices/Swiftinit.Blog.ArticlePage.swift b/Sources/SwiftinitPages/Surfaces/Vertices/Swiftinit.Blog.ArticlePage.swift
@@ -60,7 +60,7 @@ extension Swiftinit.Blog.ArticlePage:Swiftinit.StaticPage
                     $0[.h1] = self.vertex.headline.safe
 
                 }
-                $0[.section, { $0.class = "details" }]
+                $0[.section, { $0.class = "details literature" }]
                 {
                     $0 ?= (self.vertex.overview?.markdown).map(self.context.prose(_:))
                     $0 ?= (self.vertex.details?.markdown).map(self.context.prose(_:))
diff --git a/Sources/SwiftinitPages/Surfaces/Vertices/Swiftinit.Docs.ArticlePage.swift b/Sources/SwiftinitPages/Surfaces/Vertices/Swiftinit.Docs.ArticlePage.swift
@@ -82,7 +82,7 @@ extension Swiftinit.Docs.ArticlePage:Swiftinit.VertexPage
 
         main[.section] { $0.class = "notice canonical" } = self.canonical
 
-        main[.section, { $0.class = "details" }] =
+        main[.section, { $0.class = "details literature" }] =
             (self.vertex.details?.markdown).map(self.context.prose(_:))
 
         main += self.groups
diff --git a/Sources/SwiftinitPages/Surfaces/Vertices/Swiftinit.Docs.DeclPage.swift b/Sources/SwiftinitPages/Surfaces/Vertices/Swiftinit.Docs.DeclPage.swift
@@ -254,7 +254,7 @@ extension Swiftinit.Docs.DeclPage:Swiftinit.VertexPage
             }
         }
 
-        main[.section, { $0.class = "details" }]
+        main[.section, { $0.class = "details literature" }]
         {
             if  case .protocol = self.vertex.phylum
             {
diff --git a/Sources/SwiftinitPages/Surfaces/Vertices/Swiftinit.Docs.ModulePage.swift b/Sources/SwiftinitPages/Surfaces/Vertices/Swiftinit.Docs.ModulePage.swift
@@ -172,10 +172,11 @@ extension Swiftinit.Docs.ModulePage:Swiftinit.VertexPage
             default:
                 break
             }
-
-            $0 ?= (self.vertex.details?.markdown).map(self.context.prose(_:))
         }
 
+        main[.section, { $0.class = "details literature" }] =
+            (self.vertex.details?.markdown).map(self.context.prose(_:))
+
         main += self.groups
     }
 }
diff --git a/Sources/SymbolGraphLinker/Resolution/SSGC.Outliner.swift b/Sources/SymbolGraphLinker/Resolution/SSGC.Outliner.swift
@@ -106,22 +106,43 @@ extension SSGC.Outliner
             return self.outline(link: link, code: true)
 
         case .link(let link):
-            if  let colon:String.Index = link.string.firstIndex(of: ":"),
+            guard
+            let colon:String.Index = link.string.firstIndex(of: ":")
+            else
+            {
+                return self.outline(link: link, code: false)
+            }
+
+            switch link.string[..<colon]
+            {
+            case "doc":
+                let trimmed:String = .init(link.string[link.string.index(after: colon)...])
+                let link:Markdown.SourceString = .init(
+                    source: link.source,
+                    string: trimmed)
+
+                return self.outline(link: link, code: false)
+
+            case "http", "https":
+                guard
                 let start:String.Index = link.string.index(colon,
                     offsetBy: 3,
                     limitedBy: link.string.endIndex)
-            {
-                var url:Substring { link.string[start...] }
-
-                switch link.string[..<start]
+                else
                 {
-                case "https://":    return self.outline(translating: link, to: url)
-                case "http://":     return self.outline(translating: link, to: url)
-                default:            break
+                    break
                 }
+
+                return self.outline(translating: link, to: link.string[start...])
+
+            default:
+                break
             }
 
-            return self.outline(link: link, code: false)
+            self.resolver.diagnostics[link.source] =
+                InvalidAutolinkError<SSGC.Symbolicator>.init(link)
+
+            return nil
 
         case .file(let link):
             name = link
@@ -303,7 +324,7 @@ extension SSGC.Outliner
 
             for link:Markdown.InlineAutolink in topic.members
             {
-                let _:Int? = self.outline(link: link.text, code: link.code)
+                let _:Int? = self.outline(reference: .init(link))
             }
 
             let members:[SymbolGraph.Outline] = self.cache.clear()
diff --git a/Sources/UnidocQueryTests/Tests/SymbolQueries.swift b/Sources/UnidocQueryTests/Tests/SymbolQueries.swift
@@ -228,10 +228,33 @@ struct SymbolQueries:UnidocDatabaseTestBattery
         /// The type itself lives in ``BarbieHousing``, but it is namespaced to
         /// ``BarbieCore.Barbie``, and its codelinks should resolve relative to that
         /// namespace.
-        if  let tests:TestGroup = tests / "Barbie" / "Dreamhouse"
+        for case (let tests?, let path, let expected) in
+        [
+            (
+                tests / "Barbie" / "Dreamhouse",
+                ["barbiecore", "barbie", "dreamhouse"][...],
+                [
+                    "Int": [1],
+                    "Int max": [2],
+                    "ID": [1],
+                    "Barbie": [1],
+                    "Barbie ID": [2],
+                    "BarbieCore Barbie ID": [3],
+                ] as [String: [Int]]
+            ),
+            (
+                tests / "Barbie" / "Dreamhouse" / "Keys",
+                ["barbiecore", "barbie", "dreamhouse", "keys"][...],
+                [
+                    "Int": [1],
+                    "max": [2], // expands to two components because it is a vector symbol
+                    "ID": [1, 1, 1],
+                    "Barbie": [1],
+                ] as [String: [Int]]
+            ),
+        ]
         {
-            let query:Unidoc.VertexQuery<Unidoc.LookupAdjacent> = .init(
-                "swift-malibu", ["barbiecore", "barbie", "dreamhouse"])
+            let query:Unidoc.VertexQuery<Unidoc.LookupAdjacent> = .init("swift-malibu", path)
             await tests.do
             {
                 if  let output:Unidoc.VertexOutput = tests.expect(
@@ -285,7 +308,7 @@ struct SymbolQueries:UnidocDatabaseTestBattery
                         ])
 
                     let secondaries:Set<Unidoc.Scalar> = .init(output.vertices.lazy.map(\.id))
-                    let lengths:[String: Int] = overview.outlines.reduce(into: [:])
+                    let lengths:[String: [Int]] = overview.outlines.reduce(into: [:])
                     {
                         guard
                         case .path(let words, let path) = $1
@@ -299,19 +322,12 @@ struct SymbolQueries:UnidocDatabaseTestBattery
                             tests.expect(true: secondaries.contains(id))
                         }
 
-                        $0[words, default: 0] += path.count
+                        $0[words, default: []].append(path.count)
                     }
                     //  The ``Int.max`` test case is especially valuable because not only is it
                     //  a multi-component cross-package reference, but the `max` member is also
                     //  being inherited from ``SignedInteger``.
-                    tests.expect(lengths ==? [
-                            "Int": 1,
-                            "Int max": 2,
-                            "ID": 1,
-                            "Barbie": 1,
-                            "Barbie ID": 2,
-                            "BarbieCore Barbie ID": 3,
-                        ])
+                    tests.expect(lengths ==? expected)
                 }
             }
         }
diff --git a/Stylesheets/Main.scss b/Stylesheets/Main.scss
@@ -26,6 +26,7 @@
 @import 'section.group';
 @import 'section.group.dense';
 @import 'section.introduction';
+@import 'section.literature';
 @import 'section.metadata';
 @import 'Sidebar';
 @import 'Tables';
diff --git a/Stylesheets/_dl.scss b/Stylesheets/_dl.scss
@@ -10,5 +10,10 @@ dl
     dd
     {
         grid-column: 2;
+
+        > p:first-child
+        {
+            margin-top: 0;
+        }
     }
 }
diff --git a/Stylesheets/_section.details.scss b/Stylesheets/_section.details.scss
@@ -35,46 +35,26 @@ section.details
 
     section.parameters
     {
-        > h2,
-        > dl
+        > h2
         {
             padding-left: 0;
         }
         > dl
         {
             counter-set: parameter-index -1;
-            display: block;
 
             > dt
             {
                 counter-increment: parameter-index;
-                margin-top: 2rem;
-
-                font-family: $typeface-monospace;
-                font-weight: 700;
-
-                > a
-                {
-                    color: inherit;
-                }
             }
             > dt:not([id])::before, // backwards compatibility with older symbol graphs
             > dt > a::before
             {
                 content: '$' counter(parameter-index);
-                display: inline-block;
-                min-width: 3rem;
-                color: $light-snippet-line-number;
-                font-weight: normal;
-            }
-
-            > dd
-            {
-                padding-left: 3rem;
-                margin-left: 0;
             }
         }
     }
+
     section.returns
     {
         > h2
@@ -93,37 +73,5 @@ section.details
         font-size: 90.625%;
     }
 
-    aside
-    {
-        position: relative;
-        margin: 2rem 0;
-
-        h3
-        {
-            margin: 0;
-            padding: 0.5rem 0;
-            font-size: inherit;
-
-            color: $light-foreground-semi;
-            border-bottom: 2px solid $light-foreground-semi;
-        }
-
-        border-bottom: 2px solid $light-foreground-semi;
-    }
-    aside.important,
-    aside.warning
-    {
-        h3
-        {
-            color: $light-accent-hot-pink;
-            border-color: $light-accent-hot-pink;
-        }
-
-        border-color: $light-accent-hot-pink;
-    }
 
-    aside:last-child
-    {
-        border-bottom: none;
-    }
 }
diff --git a/Stylesheets/_section.literature.scss b/Stylesheets/_section.literature.scss
@@ -0,0 +1,72 @@
+@import 'Mixins/InlineCode';
+
+section.literature
+{
+    aside
+    {
+        position: relative;
+        margin: 2rem 0;
+
+        h3
+        {
+            margin: 0;
+            padding: 0.5rem 0;
+            font-size: inherit;
+
+            color: $light-foreground-semi;
+            border-bottom: 2px solid $light-foreground-semi;
+        }
+
+        border-bottom: 2px solid $light-foreground-semi;
+    }
+    aside.important,
+    aside.warning
+    {
+        h3
+        {
+            color: $light-accent-hot-pink;
+            border-color: $light-accent-hot-pink;
+        }
+
+        border-color: $light-accent-hot-pink;
+    }
+
+    aside:last-child
+    {
+        border-bottom: none;
+    }
+
+    dl
+    {
+        padding-left: 0;
+        display: block;
+
+        > dt
+        {
+            margin-top: 2rem;
+
+            font-family: $typeface-monospace;
+            font-weight: 700;
+
+            > a
+            {
+                color: inherit;
+            }
+        }
+        > dt:not([id])::before, // backwards compatibility with older symbol graphs
+        > dt > a::before
+        {
+            content: '$';
+            display: inline-block;
+            min-width: 3rem;
+            color: $light-snippet-line-number;
+            font-weight: normal;
+        }
+
+        > dd
+        {
+            padding-left: 3rem;
+            margin-left: 0;
+        }
+    }
+}
diff --git a/TestPackages/swift-malibu/Sources/BarbieHousing/Barbie.Dreamhouse.Keys.swift b/TestPackages/swift-malibu/Sources/BarbieHousing/Barbie.Dreamhouse.Keys.swift
@@ -2,7 +2,13 @@ import BarbieCore
 
 extension Barbie.Dreamhouse
 {
-    /// Keys to a dreamhouse.
+    /// We can reference the <doc:ID> type from here, even though we are in a
+    /// different module, because `Dreamhouse` is nested in the <doc:Barbie>
+    /// namespace. We can also refer to it as `<doc:Barbie/ID>, or
+    /// <doc:BarbieCore/Barbie/ID>. As an optimization, Unidoc combines multiple
+    /// occurrences of the same codelink, such as <doc:Barbie/ID>, into a single
+    /// outline. We can also reference standard library types like <doc:Int>. And we can
+    /// reference nested standard library types like <doc:Int/max>.
     public
     struct Keys
     {

Original file line number	Diff line number	Diff line change
`@@ -60,7 +60,7 @@ extension Swiftinit.Blog.ArticlePage:Swiftinit.StaticPage`
`60`	`60`	`$0[.h1] = self.vertex.headline.safe`
`61`	`61`
`62`	`62`	`}`
`63`		`- $0[.section, { $0.class = "details" }]`
	`63`	`+ $0[.section, { $0.class = "details literature" }]`
`64`	`64`	`{`
`65`	`65`	`$0 ?= (self.vertex.overview?.markdown).map(self.context.prose(_:))`
`66`	`66`	`$0 ?= (self.vertex.details?.markdown).map(self.context.prose(_:))`
Original file line number	Diff line number	Diff line change
`@@ -254,7 +254,7 @@ extension Swiftinit.Docs.DeclPage:Swiftinit.VertexPage`
`254`	`254`	`}`
`255`	`255`	`}`
`256`	`256`
`257`		`- main[.section, { $0.class = "details" }]`
	`257`	`+ main[.section, { $0.class = "details literature" }]`
`258`	`258`	`{`
`259`	`259`	`if case .protocol = self.vertex.phylum`
`260`	`260`	`{`
Original file line number	Diff line number	Diff line change
`@@ -172,10 +172,11 @@ extension Swiftinit.Docs.ModulePage:Swiftinit.VertexPage`
`172`	`172`	`default:`
`173`	`173`	`break`
`174`	`174`	`}`
`175`		`-`
`176`		`- $0 ?= (self.vertex.details?.markdown).map(self.context.prose(_:))`
`177`	`175`	`}`
`178`	`176`
	`177`	`+ main[.section, { $0.class = "details literature" }] =`
	`178`	`+ (self.vertex.details?.markdown).map(self.context.prose(_:))`
	`179`	`+`
`179`	`180`	`main += self.groups`
`180`	`181`	`}`
`181`	`182`	`}`