Skip to content

Commit c2fc598

Browse files
tayloraswifttayloraswift
committed
emit a meta description for all our doc pages
1 parent c771a8d commit c2fc598

10 files changed

+173
-25
lines changed

‎Sources/UnidocPages/API/Site.API.Get.swift

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
extension Site.API
2+
{
3+
@frozen public
4+
enum Get:String
5+
{
6+
case github
7+
case register
8+
}
9+
}
10+
extension Site.API.Get:FixedAPI
11+
{
12+
}

‎Sources/UnidocPages/API/Site.API.Post.swift

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
extension Site.API
2+
{
3+
@frozen public
4+
enum Post:String
5+
{
6+
case index
7+
}
8+
}
9+
extension Site.API.Post:FixedAPI
10+
{
11+
}

‎Sources/UnidocPages/API/Site.API.swift

Lines changed: 0 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -5,30 +5,6 @@ extension Site
55
{
66
}
77
}
8-
extension Site.API
9-
{
10-
@frozen public
11-
enum Get:String
12-
{
13-
case github
14-
case register
15-
}
16-
}
17-
extension Site.API.Get:FixedAPI
18-
{
19-
}
20-
extension Site.API
21-
{
22-
@frozen public
23-
enum Post:String
24-
{
25-
case index
26-
}
27-
}
28-
extension Site.API.Post:FixedAPI
29-
{
30-
}
31-
328
extension Site.API:FixedRoot
339
{
3410
@inlinable public static

‎Sources/UnidocPages/FixedPage.swift

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@ import URI
66
public
77
protocol FixedPage
88
{
9+
/// A short description of the page, suitable for use as a `<meta>` description.
10+
var description:String? { get }
911
var location:URI { get }
1012
var title:String { get }
1113

@@ -14,6 +16,9 @@ protocol FixedPage
1416
}
1517
extension FixedPage
1618
{
19+
@inlinable public
20+
var description:String? { nil }
21+
1722
@inlinable public
1823
func head(augmenting _:inout HTML.ContentEncoder)
1924
{
@@ -64,6 +69,11 @@ extension FixedPage
6469

6570
$0[.script] { $0.src = "\(Site.Asset[.main_js])" ; $0.defer = true }
6671

72+
if let description:String = self.description
73+
{
74+
$0[.meta] { $0.name = "description" ; $0.content = description }
75+
}
76+
6777
self.head(augmenting: &$0)
6878
}
6979

‎Sources/UnidocPages/Inlining/Inliner.Passage.swift

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -73,3 +73,36 @@ extension Inliner.Passage:HyperTextRenderableMarkdown
7373
}
7474
}
7575
}
76+
extension Inliner.Passage:PlainTextRenderableMarkdown
77+
{
78+
func load(_ reference:Int, into utf8:inout [UInt8])
79+
{
80+
guard self.outlines.indices.contains(reference)
81+
else
82+
{
83+
return
84+
}
85+
switch self.outlines[reference]
86+
{
87+
case .text(let text):
88+
utf8 += text.utf8
89+
90+
case .path(let stem, let scalars):
91+
let components:[Substring] = stem.split(separator: " ").suffix(scalars.count)
92+
var first:Bool = true
93+
for component:Substring in components
94+
{
95+
if first
96+
{
97+
first = false
98+
}
99+
else
100+
{
101+
utf8.append(0x2E)
102+
}
103+
104+
utf8 += component.utf8
105+
}
106+
}
107+
}
108+
}

‎Sources/UnidocPages/Templates/Site.Docs.Article.swift

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
import HTML
2+
import MarkdownABI
23
import MarkdownRendering
34
import UnidocRecords
45
import Unidoc
@@ -41,7 +42,12 @@ extension Site.Docs.Article
4142
extension Site.Docs.Article:FixedPage
4243
{
4344
var location:URI { Site.Docs[self.names, self.master.shoot] }
44-
var title:String { self.names.title }
45+
var title:String { "\(self.master.headline.safe) - \(self.names.title)" }
46+
47+
var description:String?
48+
{
49+
self.master.overview.map { "\(self.inliner.passage($0.markdown))" }
50+
}
4551
}
4652
extension Site.Docs.Article:ApplicationPage
4753
{

‎Sources/UnidocPages/Templates/Site.Docs.Culture.swift

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,5 @@
11
import HTML
2+
import MarkdownABI
23
import MarkdownRendering
34
import ModuleGraphs
45
import UnidocRecords
@@ -41,6 +42,25 @@ extension Site.Docs.Culture:FixedPage
4142
{
4243
var location:URI { Site.Docs[self.names, self.master.shoot] }
4344
var title:String { "\(self.name) - \(self.names.title)" }
45+
46+
var description:String?
47+
{
48+
if let overview:MarkdownBytecode = self.master.overview?.markdown
49+
{
50+
return "\(self.inliner.passage(overview))"
51+
}
52+
else if case .swift = self.names.package
53+
{
54+
return "\(self.name) is a module in the Swift standard library."
55+
}
56+
else
57+
{
58+
return """
59+
\(self.name) is a module in the \
60+
\(self.names.display ?? "\(self.names.package)") package.
61+
"""
62+
}
63+
}
4464
}
4565
extension Site.Docs.Culture:ApplicationPage
4666
{

‎Sources/UnidocPages/Templates/Site.Docs.Decl.Demonym.swift

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,49 @@ extension Site.Docs.Decl
1515
}
1616
}
1717
}
18+
extension Site.Docs.Decl.Demonym:CustomStringConvertible
19+
{
20+
var description:String
21+
{
22+
var what:String
23+
switch self.phylum
24+
{
25+
case .actor: what = "an actor"
26+
case .associatedtype: what = "an associated type"
27+
case .case: what = "an enum case"
28+
case .class: what = "a class"
29+
case .deinitializer: what = "a deinitializer"
30+
case .enum: what = "an enum"
31+
case .func(nil): what = "a global function"
32+
case .func(.class): what = "a class method"
33+
case .func(.instance): what = "an instance method"
34+
case .func(.static): what = "a static method"
35+
case .initializer: what = "an initializer"
36+
case .operator: what = "an operator"
37+
case .protocol: what = "a protocol"
38+
case .struct: what = "a struct"
39+
case .subscript(.class): what = "a class subscript"
40+
case .subscript(.instance): what = "an instance subscript"
41+
case .subscript(.static): what = "a static subscript"
42+
case .typealias: what = "a typealias"
43+
case .var(nil): what = "a global variable"
44+
case .var(.class): what = "a class property"
45+
case .var(.instance): what = "an instance property"
46+
case .var(.static): what = "a static property"
47+
}
48+
49+
if self.kinks[is: .required]
50+
{
51+
what += " requirement"
52+
}
53+
else if self.kinks[is: .intrinsicWitness]
54+
{
55+
what += " default implementation"
56+
}
57+
58+
return what
59+
}
60+
}
1861
extension Site.Docs.Decl.Demonym:HyperTextOutputStreamable
1962
{
2063
static

‎Sources/UnidocPages/Templates/Site.Docs.Decl.swift

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
import Availability
22
import HTML
33
import LexicalPaths
4+
import MarkdownABI
45
import ModuleGraphs
56
import Signatures
67
import Sources
@@ -45,6 +46,30 @@ extension Site.Docs.Decl:FixedPage
4546
{
4647
var location:URI { Site.Docs[self.names, self.master.shoot] }
4748
var title:String { "\(self.stem.last) - \(self.names.title)" }
49+
50+
var description:String?
51+
{
52+
if let overview:MarkdownBytecode = self.master.overview?.markdown
53+
{
54+
return "\(self.inliner.passage(overview))"
55+
}
56+
57+
let what:Demonym = .init(phylum: self.master.phylum, kinks: self.master.kinks)
58+
59+
if case .swift = self.names.package
60+
{
61+
return """
62+
\(self.stem.last) is \(what) from the Swift standard library.
63+
"""
64+
}
65+
else
66+
{
67+
return """
68+
\(self.stem.last) is \(what) from the package \
69+
\(self.names.display ?? "\(self.names.package)").
70+
"""
71+
}
72+
}
4873
}
4974
extension Site.Docs.Decl:ApplicationPage
5075
{

‎Sources/UnidocPages/Templates/Site.Docs.Meta.swift

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,18 @@ extension Site.Docs.Meta:FixedPage
3636
{
3737
var location:URI { Site.Docs[self.names] }
3838
var title:String { self.names.title }
39+
40+
var description:String?
41+
{
42+
self.names.package == .swift ?
43+
"""
44+
Read the documentation for version \(self.names.version) the Swift standard library.
45+
""" :
46+
"""
47+
Read the documentation for version \(self.names.version) of the \
48+
\(self.names.display ?? "\(self.names.package)") package.
49+
"""
50+
}
3951
}
4052
extension Site.Docs.Meta:ApplicationPage
4153
{

0 commit comments

Comments
 (0)