1
1
# Swift-DocC
2
2
3
- Swift-DocC is a documentation compiler for Swift frameworks and packages aimed
3
+ Swift-DocC is a documentation compiler for Swift frameworks and packages aimed
4
4
at making it easy to write and publish great developer documentation.
5
5
6
- For an example of Swift-DocC in action, check out
6
+ For an example of Swift-DocC in action, check out
7
7
[ developer.apple.com] ( https://developer.apple.com/documentation ) .
8
8
Much of Apple's developer documentation,
9
9
from [ Reference documentation] ( https://developer.apple.com/documentation/GroupActivities )
@@ -22,35 +22,35 @@ the best place to get help with Swift-DocC and discuss future plans.
22
22
23
23
## Writing and Publishing Documentation with Swift-DocC
24
24
25
- If you're looking to write and publish documentation with Swift-DocC,
25
+ If you're looking to write and publish documentation with Swift-DocC,
26
26
the best way to get started is with Swift-DocC's
27
27
[ user documentation] ( https://www.swift.org/documentation/docc ) .
28
28
29
29
## Technical Overview and Related Projects
30
30
31
- Swift-DocC builds documentation by combining _ Symbol Graph_ files containing API information
31
+ Swift-DocC builds documentation by combining _ Symbol Graph_ files containing API information
32
32
with a ` .docc ` Documentation Catalog containing articles and tutorials
33
33
to create a final archive containing the compiled documentation.
34
34
35
35
More concretely, Swift-DocC understands the following kinds of inputs:
36
36
37
37
1 . _ Symbol Graph_ files with the ` .symbols.json ` extension.
38
- _ Symbol Graph_ files are a machine-readable representation of a module's APIs,
38
+ _ Symbol Graph_ files are a machine-readable representation of a module's APIs,
39
39
including their documentation comments and relationship with one another.
40
40
41
- 2 . A Documentation Catalog with the ` .docc ` extension.
41
+ 2 . A Documentation Catalog with the ` .docc ` extension.
42
42
Documentation Catalogs can include additional documentation content like the following:
43
-
43
+
44
44
- Documentation markup files with the ` .md ` extension. Documentation markup files can
45
45
be used to extend documentation for symbols and to write free-form articles.
46
-
46
+
47
47
- Tutorial files with the ` .tutorial ` extension. Tutorial files are used to author
48
48
step-by-step instructions on how to use a framework.
49
-
49
+
50
50
- Additional documentation assets with known extensions like ` .png ` , ` .jpg ` , ` .mov ` ,
51
51
and ` .zip ` .
52
-
53
- - An ` Info.plist ` file containing metadata such as the name of the documented module.
52
+
53
+ - An ` Info.plist ` file containing metadata such as the name of the documented module.
54
54
This file is optional and the information it contains can be passed via the command line.
55
55
56
56
Swift-DocC outputs a machine-readable archive of the compiled documentation.
@@ -66,27 +66,27 @@ project's technical documentation:
66
66
67
67
### Related Projects
68
68
69
- - As of Swift 5.5, the [ Swift Compiler] ( https://github.com/apple/swift ) is able to
69
+ - As of Swift 5.5, the [ Swift Compiler] ( https://github.com/apple/swift ) is able to
70
70
emit _ Symbol Graph_ files as part of the compilation process.
71
-
71
+
72
72
- [ SymbolKit] ( https://github.com/apple/swift-docc-symbolkit ) is a Swift package containing
73
73
the specification and reference model for the _ Symbol Graph_ File Format.
74
-
75
- - [ Swift Markdown] ( https://github.com/apple/swift-markdown ) is a
76
- Swift package for parsing, building, editing, and analyzing
74
+
75
+ - [ Swift Markdown] ( https://github.com/apple/swift-markdown ) is a
76
+ Swift package for parsing, building, editing, and analyzing
77
77
Markdown documents. It includes support for the Block Directive elements
78
78
that Swift-DocC's tutorial files rely on.
79
-
80
- - [ Swift-DocC-Render] ( https://github.com/apple/swift-docc-render )
79
+
80
+ - [ Swift-DocC-Render] ( https://github.com/apple/swift-docc-render )
81
81
is a web application that understands and renders
82
82
Swift-DocC's _ render JSON_ format.
83
-
83
+
84
84
- [ Xcode] ( https://developer.apple.com/xcode/ ) consists of a suite of
85
85
tools that developers use to build apps for Apple platforms.
86
86
Beginning with Xcode 13, Swift-DocC is integrated into Xcode
87
87
with support for building and viewing documentation for your framework and
88
88
its dependencies.
89
-
89
+
90
90
## Getting started with developing ` docc `
91
91
92
92
` docc ` is the command line interface (CLI) for Swift-DocC and provides
@@ -128,17 +128,17 @@ To run `docc`, run the following command:
128
128
` ` ` bash
129
129
swift run docc
130
130
` ` `
131
-
131
+
132
132
# ## Installing into Xcode
133
133
134
134
You can test a locally built version of Swift-DocC in Xcode 13 or later by setting
135
135
the ` DOCC_EXEC` build setting to the path of your local ` docc` :
136
136
137
137
1. Select the project in the Project Navigator.
138
-
139
- 2. In the Build Settings tab, click ' +' and then ' Add User-Defined Setting' .
140
-
141
- 3. Create a build setting ` DOCC_EXEC` with the value set to ` /path/to/docc` .
138
+
139
+ 2. In the Build Settings tab, click ' +' and then ' Add User-Defined Setting' .
140
+
141
+ 3. Create a build setting ` DOCC_EXEC` with the value set to ` /path/to/docc` .
142
142
143
143
The next time you invoke a documentation build with the " Build Documentation"
144
144
button in Xcode' s Product menu, your custom `docc` will be used for the build.
@@ -160,19 +160,19 @@ the path you provded if it's set.
160
160
## Using `docc` to build and preview documentation
161
161
162
162
The preferred way of building documentation for your Swift package is by using
163
- the Swift-DocC Plugin, or if you' re using Xcode, using the " Build Documentation" command.
163
+ the Swift-DocC Plugin, or if you' re using Xcode, using the " Build Documentation" command.
164
164
165
- Refer to instructions in the plugin' s
165
+ Refer to instructions in the plugin' s
166
166
[documentation](https://apple.github.io/swift-docc-plugin/documentation/swiftdoccplugin/)
167
167
to get started with [building](https://apple.github.io/swift-docc-plugin/documentation/swiftdoccplugin/generating-documentation-for-a-specific-target), [previewing](https://apple.github.io/swift-docc-plugin/documentation/swiftdoccplugin/previewing-documentation),
168
168
and publishing your documentation to your [website](https://apple.github.io/swift-docc-plugin/documentation/swiftdoccplugin/generating-documentation-for-hosting-online) or [GitHub Pages](https://apple.github.io/swift-docc-plugin/documentation/swiftdoccplugin/publishing-to-github-pages).
169
169
170
- Alternatively, you can manually generate symbol graph files and invoke `docc` directly.
170
+ Alternatively, you can manually generate symbol graph files and invoke `docc` directly.
171
171
Refer to instructions in [CONTRIBUTING.md](/CONTRIBUTING.md#assembling-symbol-graphs-and-building-with-docc-directly).
172
-
172
+
173
173
## Versioning
174
174
175
- Swift-DocC' s CLI tool (` docc` ) will be integrated into the Swift toolchain
175
+ Swift-DocC' s CLI tool (` docc` ) will be integrated into the Swift toolchain
176
176
and follows the Swift compiler' s versioning scheme.
177
177
178
178
The `SwiftDocC` library is versioned separately from `docc`. `SwiftDocC` is under
@@ -182,7 +182,7 @@ active development and source stability is not guaranteed.
182
182
183
183
### Submitting a Bug Report
184
184
185
- Swift-DocC tracks all bug reports with
185
+ Swift-DocC tracks all bug reports with
186
186
[GitHub Issues](https://github.com/apple/swift-docc/issues).
187
187
When you submit a bug report we ask that you follow the
188
188
[provided template](https://github.com/apple/swift-docc/issues/new?assignees=&labels=bug&template=BUG_REPORT.yml)
@@ -191,7 +191,7 @@ and provide as many details as possible.
191
191
> **Note:** You can use the [`environment`](bin/environment) script
192
192
> in this repository to gather helpful environment information to paste
193
193
> into your bug report by running the following:
194
- >
194
+ >
195
195
> ```sh
196
196
> bin/environment
197
197
> ```
0 commit comments