Skip to content

Commit 2cff0b0

Browse files
heckjJacobHearstpatshaughnessyd-ronnqvist
authored
[docs] Add basic documentation on using Snippets to DocC documentation (#1166)
* Initial work on snippets documentation Co-authored-by: Joe Heck <heckj@mac.com> Co-authored-by: Jacob Hearst <jacob@hearst.dev> * consolidate copyright statements at bottom of markdown files and add a newline to the end of the file * enables Snippet directive code for documentation, and updates the generated symbolgraph with that change * updating with an overview * fixing license header for check script * Update Sources/docc/DocCDocumentation.docc/DocC Documentation.md Co-authored-by: Pat Shaughnessy <pat_shaughnessy@apple.com> * Update Sources/docc/DocCDocumentation.docc/snippets.md Co-authored-by: Pat Shaughnessy <pat_shaughnessy@apple.com> * Update Sources/docc/DocCDocumentation.docc/Reference Syntax/API Reference Syntax/Snippet.md Co-authored-by: Pat Shaughnessy <pat_shaughnessy@apple.com> * renaming article per feedback * update documentation to explicitly call out adding swift-docc-plugin dependency * Add an ASCII diagram of an example Swift package directory structure, to make it clear where the snippets go, and also where the documentation catalog goes. Also show a concrete example of how to reference a snippet. Fix a typo. * Include a full markdown example containing @snippet * applying updates based on David's feedback * co-locates snippet API ref content to source class rather than using an extension page * revising note about snippets vs. docc catalogs and target linkage * Update Sources/docc/DocCDocumentation.docc/adding-code-snippets-to-your-content.md Co-authored-by: David Rönnqvist <ronnqvist@apple.com> * removing section about markdown comments inside snippets * collapsing some of the demo material down per David's feedback --------- Co-authored-by: Jacob Hearst <jacob@hearst.dev> Co-authored-by: Pat Shaughnessy <pat_shaughnessy@apple.com> Co-authored-by: David Rönnqvist <ronnqvist@apple.com>
1 parent 9cd9bc3 commit 2cff0b0

File tree

4 files changed

+429
-3
lines changed

4 files changed

+429
-3
lines changed

‎Sources/SwiftDocC/Semantics/Snippets/Snippet.swift‎

Lines changed: 18 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -12,8 +12,25 @@ import Foundation
1212
public import Markdown
1313
import SymbolKit
1414

15+
/// Embeds a code example from the project's code snippets.
16+
///
17+
/// ```markdown
18+
/// @Snippet(path: "my-package/Snippets/example-snippet", slice: "setup")
19+
/// ```
20+
///
21+
/// Place the `Snippet` directive to embed a code example from the project's snippet directory.
22+
/// The path that references the snippet is identified with three parts:
23+
///
24+
/// 1. The package name as defined in `Package.swift`
25+
///
26+
/// 2. The directory path to the snippet file, starting with "Snippets".
27+
///
28+
/// 3. The name of your snippet file without the `.swift` extension
29+
///
30+
/// If the snippet had slices annotated within it, an individual slice of the snippet can be referenced with the `slice` option.
31+
/// Without the option defined, the directive embeds the entire snippet.
1532
public final class Snippet: Semantic, AutomaticDirectiveConvertible {
16-
public static let introducedVersion = "5.6"
33+
public static let introducedVersion = "5.7"
1734
public let originalMarkup: BlockDirective
1835

1936
/// The path components of a symbol link that would be used to resolve a reference to a snippet,
@@ -30,8 +47,6 @@ public final class Snippet: Semantic, AutomaticDirectiveConvertible {
3047
"slice" : \Snippet._slice,
3148
]
3249

33-
static var hiddenFromDocumentation = true
34-
3550
@available(*, deprecated, message: "Do not call directly. Required for 'AutomaticDirectiveConvertible'.")
3651
init(originalMarkup: BlockDirective) {
3752
self.originalMarkup = originalMarkup

‎Sources/docc/DocCDocumentation.docc/DocC Documentation.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,7 @@ DocC syntax — called _documentation markup_ — is a custom variant of Markdow
2525
- <doc:writing-symbol-documentation-in-your-source-files>
2626
- <doc:adding-supplemental-content-to-a-documentation-catalog>
2727
- <doc:linking-to-symbols-and-other-content>
28+
- <doc:adding-code-snippets-to-your-content>
2829
- <doc:documenting-api-with-different-language-representations>
2930

3031
### Structure and Formatting

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

Lines changed: 207 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5246,6 +5246,213 @@
52465246
"Small"
52475247
]
52485248
},
5249+
{
5250+
"accessLevel" : "public",
5251+
"availability" : [
5252+
{
5253+
"domain" : "Swift-DocC",
5254+
"introduced" : {
5255+
"major" : 5,
5256+
"minor" : 7,
5257+
"patch" : 0
5258+
}
5259+
}
5260+
],
5261+
"declarationFragments" : [
5262+
{
5263+
"kind" : "typeIdentifier",
5264+
"spelling" : "@"
5265+
},
5266+
{
5267+
"kind" : "typeIdentifier",
5268+
"spelling" : "Snippet"
5269+
},
5270+
{
5271+
"kind" : "text",
5272+
"spelling" : "("
5273+
},
5274+
{
5275+
"kind" : "identifier",
5276+
"spelling" : "path"
5277+
},
5278+
{
5279+
"kind" : "text",
5280+
"spelling" : ": "
5281+
},
5282+
{
5283+
"kind" : "typeIdentifier",
5284+
"spelling" : "String"
5285+
},
5286+
{
5287+
"kind" : "text",
5288+
"spelling" : ", "
5289+
},
5290+
{
5291+
"kind" : "identifier",
5292+
"spelling" : "slice"
5293+
},
5294+
{
5295+
"kind" : "text",
5296+
"spelling" : ": "
5297+
},
5298+
{
5299+
"kind" : "typeIdentifier",
5300+
"spelling" : "String"
5301+
},
5302+
{
5303+
"kind" : "text",
5304+
"spelling" : "?"
5305+
},
5306+
{
5307+
"kind" : "text",
5308+
"spelling" : ")"
5309+
}
5310+
],
5311+
"docComment" : {
5312+
"lines" : [
5313+
{
5314+
"text" : "Embeds a code example from the project's code snippets."
5315+
},
5316+
{
5317+
"text" : ""
5318+
},
5319+
{
5320+
"text" : "```markdown"
5321+
},
5322+
{
5323+
"text" : "@Snippet(path: \"my-package\/Snippets\/example-snippet\", slice: \"setup\")"
5324+
},
5325+
{
5326+
"text" : "```"
5327+
},
5328+
{
5329+
"text" : ""
5330+
},
5331+
{
5332+
"text" : "Place the `Snippet` directive to embed a code example from the project's snippet directory."
5333+
},
5334+
{
5335+
"text" : "The path that references the snippet is identified with three parts:"
5336+
},
5337+
{
5338+
"text" : ""
5339+
},
5340+
{
5341+
"text" : "1. The package name as defined in `Package.swift`"
5342+
},
5343+
{
5344+
"text" : ""
5345+
},
5346+
{
5347+
"text" : "2. The directory path to the snippet file, starting with \"Snippets\"."
5348+
},
5349+
{
5350+
"text" : ""
5351+
},
5352+
{
5353+
"text" : "3. The name of your snippet file without the `.swift` extension"
5354+
},
5355+
{
5356+
"text" : ""
5357+
},
5358+
{
5359+
"text" : "If the snippet had slices annotated within it, an individual slice of the snippet can be referenced with the `slice` option."
5360+
},
5361+
{
5362+
"text" : "Without the option defined, the directive embeds the entire snippet."
5363+
},
5364+
{
5365+
"text" : "- Parameters:"
5366+
},
5367+
{
5368+
"text" : " - path: The path components of a symbol link that would be used to resolve a reference to a snippet,"
5369+
},
5370+
{
5371+
"text" : " only occurring as a block directive argument."
5372+
},
5373+
{
5374+
"text" : " **(required)**"
5375+
},
5376+
{
5377+
"text" : " - slice: An optional named range to limit the lines shown."
5378+
},
5379+
{
5380+
"text" : " **(optional)**"
5381+
}
5382+
]
5383+
},
5384+
"identifier" : {
5385+
"interfaceLanguage" : "swift",
5386+
"precise" : "__docc_universal_symbol_reference_$Snippet"
5387+
},
5388+
"kind" : {
5389+
"displayName" : "Directive",
5390+
"identifier" : "class"
5391+
},
5392+
"names" : {
5393+
"navigator" : [
5394+
{
5395+
"kind" : "attribute",
5396+
"spelling" : "@"
5397+
},
5398+
{
5399+
"kind" : "identifier",
5400+
"preciseIdentifier" : "__docc_universal_symbol_reference_$Snippet",
5401+
"spelling" : "Snippet"
5402+
}
5403+
],
5404+
"subHeading" : [
5405+
{
5406+
"kind" : "identifier",
5407+
"spelling" : "@"
5408+
},
5409+
{
5410+
"kind" : "identifier",
5411+
"spelling" : "Snippet"
5412+
},
5413+
{
5414+
"kind" : "text",
5415+
"spelling" : "("
5416+
},
5417+
{
5418+
"kind" : "identifier",
5419+
"spelling" : "path"
5420+
},
5421+
{
5422+
"kind" : "text",
5423+
"spelling" : ": "
5424+
},
5425+
{
5426+
"kind" : "typeIdentifier",
5427+
"spelling" : "String"
5428+
},
5429+
{
5430+
"kind" : "text",
5431+
"spelling" : ", "
5432+
},
5433+
{
5434+
"kind" : "identifier",
5435+
"spelling" : "slice"
5436+
},
5437+
{
5438+
"kind" : "text",
5439+
"spelling" : ": "
5440+
},
5441+
{
5442+
"kind" : "typeIdentifier",
5443+
"spelling" : "String"
5444+
},
5445+
{
5446+
"kind" : "text",
5447+
"spelling" : ")"
5448+
}
5449+
],
5450+
"title" : "Snippet"
5451+
},
5452+
"pathComponents" : [
5453+
"Snippet"
5454+
]
5455+
},
52495456
{
52505457
"accessLevel" : "public",
52515458
"availability" : [

0 commit comments

Comments
 (0)