Skip to content

Commit 438c334

Browse files
committed
update documentation to explicitly call out adding swift-docc-plugin dependency
1 parent 5ddfd8c commit 438c334

File tree

1 file changed

+34
-4
lines changed

1 file changed

+34
-4
lines changed

Sources/docc/DocCDocumentation.docc/adding-code-snippets-to-your-content.md

Lines changed: 34 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
# Adding Code Snippets to your Content
22

3+
@Metadata {
4+
@Available("Swift", introduced: "5.7")
5+
}
6+
37
Create and include code snippets to illustrate and provide examples of how to use your API.
48

59
## Overview
@@ -11,6 +15,31 @@ Swift Package Manager looks for, and builds, any code included in the `Snippets`
1115
DocC supports referencing all, or parts, of those files to present as code listings.
1216
This allows you to verify that code examples, referenced in your documentation, continue to compile as you evolve you app or library.
1317

18+
### Add the Swift DocC plugin
19+
20+
To generate or preview documentation with snippets, add [swift-docc-plugin](https://github.com/apple/swift-docc-plugin) as a dependency to your package.
21+
22+
For example, use the command:
23+
24+
```bash
25+
swift package add-dependency https://github.com/apple/swift-docc-plugin --from 1.1.0
26+
```
27+
28+
Or edit your `Package.swift` to add the dependency:
29+
30+
```
31+
let package = Package(
32+
// name, platforms, products, etc.
33+
dependencies: [
34+
// other dependencies
35+
.package(url: "https://github.com/swiftlang/swift-docc-plugin", from: "1.1.0"),
36+
],
37+
targets: [
38+
// targets
39+
]
40+
)
41+
```
42+
1443
### Create a code snippet
1544

1645
Swift Package Manager expects to find your code examples in the directory `Snippets` at the top of your project, parallel to the file `Package.swift` and the directory `Sources`.
@@ -72,16 +101,17 @@ print("Hidden")
72101
print("Shown")
73102
```
74103

75-
Hide segments of your snippet for things like license footers, test code, or unique setup code.
76-
Generally, it is mostly useful for things that you wouldn't want the reader to take with them as a starting point.
104+
Hide segments of your snippet for content such as license footers, test code, or unique setup code.
105+
Generally, it is useful for things that you wouldn't want the reader to use as a starting point.
77106

78107
### Preview your content
79108

80109
Use the [swift-docc-plugin](https://github.com/swiftlang/swift-docc-plugin) to preview content that includes snippets.
81-
To run the preview, use the following command from a terminal:
110+
To run the preview, use the following command from a terminal.
111+
Replace `YourTarget` with a target from your package to preview:
82112

83113
```bash
84-
swift package --disable-sandbox preview-documentation
114+
swift package --disable-sandbox preview-documentation --target YourTarget
85115
```
86116

87117
### Slice up your snippet to break it up in your content.

0 commit comments

Comments
 (0)