Skip to content

Commit 21c3e25

Browse files
patshaughnessypatshaughnessy
authored
R117883810 @redirected placement (#805)
* DocumentationMarkup removes @redirected directives from the content while parsing titles, abstracts and discussions, allowing them to appear anywhere after the title. * Allow @redirected to be child directives of @metadata. * Document the @redirected directive. * Test helpers in DocumentationMarkupTests use file and line number parameters. * Modified files were updated in 2024 * Fix code alignment in Metadata.swift
1 parent 9c79734 commit 21c3e25

File tree

11 files changed

+400
-17
lines changed

11 files changed

+400
-17
lines changed

‎Sources/SwiftDocC/Model/DocumentationMarkup.swift

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
/*
22
This source file is part of the Swift.org open source project
33

4-
Copyright (c) 2021 Apple Inc. and the Swift project authors
4+
Copyright (c) 2021-2024 Apple Inc. and the Swift project authors
55
Licensed under Apache License v2.0 with Runtime Library Exception
66

77
See https://swift.org/LICENSE.txt for license information
@@ -73,6 +73,14 @@ struct DocumentationMarkup {
7373
case end
7474
}
7575

76+
/// Directives which are removed from the markdown content after being parsed.
77+
private static let directivesRemovedFromContent = [
78+
Comment.directiveName,
79+
Metadata.directiveName,
80+
Options.directiveName,
81+
Redirect.directiveName,
82+
]
83+
7684
// MARK: - Parsed Data
7785

7886
/// The documentation title, if found.
@@ -146,7 +154,7 @@ struct DocumentationMarkup {
146154
// Found deprecation notice in the abstract.
147155
deprecation = MarkupContainer(directive.children)
148156
return
149-
} else if directive.name == Comment.directiveName || directive.name == Metadata.directiveName || directive.name == Options.directiveName {
157+
} else if Self.directivesRemovedFromContent.contains(directive.name) {
150158
// These directives don't affect content so they shouldn't break us out of
151159
// the automatic abstract section.
152160
return

‎Sources/SwiftDocC/Semantics/Article/Article.swift

Lines changed: 8 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -121,7 +121,7 @@ public final class Article: Semantic, MarkupConvertible, Abstracted, Redirected,
121121
}
122122

123123
var remainder: [Markup]
124-
let redirects: [Redirect]
124+
var redirects: [Redirect]
125125
(redirects, remainder) = markup.children.categorize { child -> Redirect? in
126126
guard let childDirective = child as? BlockDirective, childDirective.name == Redirect.directiveName else {
127127
return nil
@@ -142,7 +142,13 @@ public final class Article: Semantic, MarkupConvertible, Abstracted, Redirected,
142142
}
143143

144144
var optionalMetadata = metadata.first
145-
145+
146+
// Append any redirects found in the metadata to the redirects
147+
// found in the main content.
148+
if let redirectsFromMetadata = optionalMetadata?.redirects {
149+
redirects.append(contentsOf: redirectsFromMetadata)
150+
}
151+
146152
let options: [Options]
147153
(options, remainder) = remainder.categorize { child -> Options? in
148154
guard let childDirective = child as? BlockDirective, childDirective.name == Options.directiveName else {

‎Sources/SwiftDocC/Semantics/Metadata/Metadata.swift

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -74,7 +74,10 @@ public final class Metadata: Semantic, AutomaticDirectiveConvertible {
7474

7575
@ChildDirective
7676
var titleHeading: TitleHeading? = nil
77-
77+
78+
@ChildDirective
79+
var redirects: [Redirect]? = nil
80+
7881
static var keyPaths: [String : AnyKeyPath] = [
7982
"documentationOptions" : \Metadata._documentationOptions,
8083
"technologyRoot" : \Metadata._technologyRoot,
@@ -87,6 +90,7 @@ public final class Metadata: Semantic, AutomaticDirectiveConvertible {
8790
"supportedLanguages" : \Metadata._supportedLanguages,
8891
"_pageColor" : \Metadata.__pageColor,
8992
"titleHeading" : \Metadata._titleHeading,
93+
"redirects" : \Metadata._redirects,
9094
]
9195

9296
@available(*, deprecated, message: "Do not call directly. Required for 'AutomaticDirectiveConvertible'.")
@@ -96,7 +100,7 @@ public final class Metadata: Semantic, AutomaticDirectiveConvertible {
96100

97101
func validate(source: URL?, for bundle: DocumentationBundle, in context: DocumentationContext, problems: inout [Problem]) -> Bool {
98102
// Check that something is configured in the metadata block
99-
if documentationOptions == nil && technologyRoot == nil && displayName == nil && pageImages.isEmpty && customMetadata.isEmpty && callToAction == nil && availability.isEmpty && pageKind == nil && pageColor == nil && titleHeading == nil {
103+
if documentationOptions == nil && technologyRoot == nil && displayName == nil && pageImages.isEmpty && customMetadata.isEmpty && callToAction == nil && availability.isEmpty && pageKind == nil && pageColor == nil && titleHeading == nil && redirects == nil {
100104
let diagnostic = Diagnostic(
101105
source: source,
102106
severity: .information,

‎Sources/SwiftDocC/Semantics/Redirect.swift

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
/*
22
This source file is part of the Swift.org open source project
33

4-
Copyright (c) 2021-2023 Apple Inc. and the Swift project authors
4+
Copyright (c) 2021-2024 Apple Inc. and the Swift project authors
55
Licensed under Apache License v2.0 with Runtime Library Exception
66

77
See https://swift.org/LICENSE.txt for license information
@@ -18,6 +18,10 @@ import Markdown
1818
/// For example, if you host the compiled documentation on a web server,
1919
/// that server can read this data and set an HTTP "301 Moved Permanently" redirect from
2020
/// the declared URL to the page's current URL and avoid breaking any existing links to the content.
21+
///
22+
/// > Note: Starting with version 5.11, @Redirected is supported as a child directive of @Metadata. In
23+
/// previous versions, @Redirected must be used as a top level directive.
24+
///
2125
public final class Redirect: Semantic, AutomaticDirectiveConvertible {
2226
public static let introducedVersion = "5.5"
2327
public static let directiveName = "Redirected"
@@ -31,7 +35,7 @@ public final class Redirect: Semantic, AutomaticDirectiveConvertible {
3135
"oldPath" : \Redirect._oldPath,
3236
]
3337

34-
static var hiddenFromDocumentation = true
38+
static var hiddenFromDocumentation = false
3539

3640
init(originalMarkup: BlockDirective, oldPath: URL) {
3741
self.originalMarkup = originalMarkup

‎Sources/docc/DocCDocumentation.docc/DocC.symbols.json

Lines changed: 141 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4043,6 +4043,147 @@
40434043
"PageKind"
40444044
]
40454045
},
4046+
{
4047+
"accessLevel" : "public",
4048+
"availability" : [
4049+
{
4050+
"domain" : "Swift-DocC",
4051+
"introduced" : {
4052+
"major" : 5,
4053+
"minor" : 5,
4054+
"patch" : 0
4055+
}
4056+
}
4057+
],
4058+
"declarationFragments" : [
4059+
{
4060+
"kind" : "typeIdentifier",
4061+
"spelling" : "@"
4062+
},
4063+
{
4064+
"kind" : "typeIdentifier",
4065+
"spelling" : "Redirected"
4066+
},
4067+
{
4068+
"kind" : "text",
4069+
"spelling" : "("
4070+
},
4071+
{
4072+
"kind" : "identifier",
4073+
"spelling" : "from"
4074+
},
4075+
{
4076+
"kind" : "text",
4077+
"spelling" : ": "
4078+
},
4079+
{
4080+
"kind" : "typeIdentifier",
4081+
"spelling" : "URL"
4082+
},
4083+
{
4084+
"kind" : "text",
4085+
"spelling" : ")"
4086+
}
4087+
],
4088+
"docComment" : {
4089+
"lines" : [
4090+
{
4091+
"text" : "A directive that specifies an additional URL for the page where the directive appears."
4092+
},
4093+
{
4094+
"text" : ""
4095+
},
4096+
{
4097+
"text" : "Use this directive to declare a URL where a piece of content was previously located."
4098+
},
4099+
{
4100+
"text" : "For example, if you host the compiled documentation on a web server,"
4101+
},
4102+
{
4103+
"text" : "that server can read this data and set an HTTP \"301 Moved Permanently\" redirect from"
4104+
},
4105+
{
4106+
"text" : "the declared URL to the page's current URL and avoid breaking any existing links to the content."
4107+
},
4108+
{
4109+
"text" : ""
4110+
},
4111+
{
4112+
"text" : "> Note: Starting with version 5.11, @Redirected is supported as a child directive of @Metadata. In"
4113+
},
4114+
{
4115+
"text" : "previous versions, @Redirected must be used as a top level directive."
4116+
},
4117+
{
4118+
"text" : ""
4119+
},
4120+
{
4121+
"text" : "- Parameters:"
4122+
},
4123+
{
4124+
"text" : " - from: The URL that redirects to the page associated with the directive."
4125+
},
4126+
{
4127+
"text" : " **(required)**"
4128+
}
4129+
]
4130+
},
4131+
"identifier" : {
4132+
"interfaceLanguage" : "swift",
4133+
"precise" : "__docc_universal_symbol_reference_$Redirected"
4134+
},
4135+
"kind" : {
4136+
"displayName" : "Directive",
4137+
"identifier" : "class"
4138+
},
4139+
"names" : {
4140+
"navigator" : [
4141+
{
4142+
"kind" : "attribute",
4143+
"spelling" : "@"
4144+
},
4145+
{
4146+
"kind" : "identifier",
4147+
"preciseIdentifier" : "__docc_universal_symbol_reference_$Redirected",
4148+
"spelling" : "Redirected"
4149+
}
4150+
],
4151+
"subHeading" : [
4152+
{
4153+
"kind" : "identifier",
4154+
"spelling" : "@"
4155+
},
4156+
{
4157+
"kind" : "identifier",
4158+
"spelling" : "Redirected"
4159+
},
4160+
{
4161+
"kind" : "text",
4162+
"spelling" : "("
4163+
},
4164+
{
4165+
"kind" : "identifier",
4166+
"spelling" : "from"
4167+
},
4168+
{
4169+
"kind" : "text",
4170+
"spelling" : ": "
4171+
},
4172+
{
4173+
"kind" : "typeIdentifier",
4174+
"spelling" : "URL"
4175+
},
4176+
{
4177+
"kind" : "text",
4178+
"spelling" : ")"
4179+
}
4180+
],
4181+
"title" : "Redirected"
4182+
},
4183+
"pathComponents" : [
4184+
"Redirected"
4185+
]
4186+
},
40464187
{
40474188
"accessLevel" : "public",
40484189
"availability" : [

‎Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/Metadata.md

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,20 @@ Use the `Metadata` directive with the ``TitleHeading`` directive to configure th
4040
}
4141
```
4242
43+
Starting with version 5.11, use the `Metadata` directive with one or more ``Redirected`` directives
44+
to add additional URLs for a page.
45+
```
46+
# ``SlothCreator``
47+
48+
@Metadata {
49+
@Redirected(from: "old/path/to/page")
50+
@Redirected(from: "another/old/path/to/page")
51+
}
52+
```
53+
54+
> Note: Starting with version 5.11, @Redirected is supported as a child directive of @Metadata. In
55+
previous versions, @Redirected must be used as a top level directive.
56+
4357
## Topics
4458
4559
### Extending or Overriding Source Documentation
@@ -67,4 +81,11 @@ Use the `Metadata` directive with the ``TitleHeading`` directive to configure th
6781
6882
- ``Available``
6983
84+
### Specifying an Additional URL of a Page
85+
86+
- ``Redirected``
87+
88+
> Note: Starting with version 5.11, @Redirected is supported as a child directive of @Metadata. In
89+
previous versions, @Redirected must be used as a top level directive.
90+
7091
<!-- Copyright (c) 2021-2023 Apple Inc and the Swift Project authors. All Rights Reserved. -->

‎Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/api-reference-syntax.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ Use documentation markup, a custom variant of Markdown, to add in-source documen
1515
- ``Options``
1616
- ``Metadata``
1717
- ``TechnologyRoot``
18+
- ``Redirected``
1819

1920
### Creating Custom Page Layouts
2021

0 commit comments

Comments
 (0)