You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: Sources/docc/DocCDocumentation.docc/adding-code-snippets-to-your-content.md
+34-4Lines changed: 34 additions & 4 deletions
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,9 @@
1
1
# Adding Code Snippets to your Content
2
2
3
+
@Metadata {
4
+
@Available("Swift", introduced: "5.7")
5
+
}
6
+
3
7
Create and include code snippets to illustrate and provide examples of how to use your API.
4
8
5
9
## Overview
@@ -11,6 +15,31 @@ Swift Package Manager looks for, and builds, any code included in the `Snippets`
11
15
DocC supports referencing all, or parts, of those files to present as code listings.
12
16
This allows you to verify that code examples, referenced in your documentation, continue to compile as you evolve you app or library.
13
17
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:
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")
72
101
print("Shown")
73
102
```
74
103
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.
77
106
78
107
### Preview your content
79
108
80
109
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:
82
112
83
113
```bash
84
-
swift package --disable-sandbox preview-documentation
114
+
swift package --disable-sandbox preview-documentation --target YourTarget
85
115
```
86
116
87
117
### Slice up your snippet to break it up in your content.
0 commit comments