jazzy 0.14.4 → 0.15.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/.github/workflows/Tests.yml +6 -5
- data/.rubocop.yml +13 -0
- data/CHANGELOG.md +40 -0
- data/CONTRIBUTING.md +1 -1
- data/Gemfile.lock +62 -47
- data/README.md +115 -5
- data/bin/sourcekitten +0 -0
- data/js/package-lock.json +6 -6
- data/lib/jazzy/config.rb +156 -24
- data/lib/jazzy/doc.rb +2 -2
- data/lib/jazzy/doc_builder.rb +55 -29
- data/lib/jazzy/doc_index.rb +185 -0
- data/lib/jazzy/docset_builder/info_plist.mustache +1 -1
- data/lib/jazzy/docset_builder.rb +44 -13
- data/lib/jazzy/extensions/katex/css/katex.min.css +1 -1
- data/lib/jazzy/extensions/katex/js/katex.min.js +1 -1
- data/lib/jazzy/gem_version.rb +1 -1
- data/lib/jazzy/grouper.rb +130 -0
- data/lib/jazzy/podspec_documenter.rb +1 -1
- data/lib/jazzy/source_declaration/type.rb +10 -2
- data/lib/jazzy/source_declaration.rb +69 -8
- data/lib/jazzy/source_document.rb +5 -1
- data/lib/jazzy/source_module.rb +13 -11
- data/lib/jazzy/sourcekitten.rb +231 -237
- data/lib/jazzy/symbol_graph/ext_key.rb +37 -0
- data/lib/jazzy/symbol_graph/ext_node.rb +23 -6
- data/lib/jazzy/symbol_graph/graph.rb +31 -19
- data/lib/jazzy/symbol_graph/relationship.rb +21 -3
- data/lib/jazzy/symbol_graph/sym_node.rb +10 -22
- data/lib/jazzy/symbol_graph/symbol.rb +28 -0
- data/lib/jazzy/symbol_graph.rb +19 -16
- data/lib/jazzy/themes/apple/assets/css/jazzy.css.scss +10 -7
- data/lib/jazzy/themes/apple/assets/js/typeahead.jquery.js +3 -2
- data/lib/jazzy/themes/apple/templates/doc.mustache +8 -1
- data/lib/jazzy/themes/fullwidth/assets/css/jazzy.css.scss +5 -5
- data/lib/jazzy/themes/fullwidth/assets/js/typeahead.jquery.js +3 -2
- data/lib/jazzy/themes/fullwidth/templates/doc.mustache +8 -1
- data/lib/jazzy/themes/jony/assets/css/jazzy.css.scss +6 -5
- data/lib/jazzy/themes/jony/templates/doc.mustache +9 -2
- data/spec/integration_spec.rb +8 -1
- metadata +5 -2
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: a4e56611ebbc1fd23b15eb87740d56ca89523b6d98a9d1c7a8219fdc62e8b3d4
|
4
|
+
data.tar.gz: d3ffb914f1df703944287fa69b00e4c68b734076eeb825a2ab59857f27d28f6d
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: c3418c7fe4eb7f9d1a83316fc3df22d0e7c87f42487f74ab62cc94e3b47e6e6c644327ef59ea5e4abae9a074b8adcf63da3c757df421a888220cdd4b039c6e5c
|
7
|
+
data.tar.gz: 2c28f8a6b6b8f4537cf35b30bfb89690ac5efd9b492a420b1bd1bb7184e8a665c91ae6ca31e473cce386bee30c1001cc4d90900a5b914b6da0aa6cc8072668e7
|
data/.github/workflows/Tests.yml
CHANGED
@@ -10,7 +10,7 @@ jobs:
|
|
10
10
|
danger_and_rubocop:
|
11
11
|
runs-on: ubuntu-latest
|
12
12
|
steps:
|
13
|
-
- uses: actions/checkout@
|
13
|
+
- uses: actions/checkout@v4
|
14
14
|
- uses: ruby/setup-ruby@v1
|
15
15
|
with:
|
16
16
|
ruby-version: 3.2
|
@@ -25,17 +25,18 @@ jobs:
|
|
25
25
|
bundle exec danger --verbose
|
26
26
|
|
27
27
|
spec:
|
28
|
-
runs-on: macos-
|
28
|
+
runs-on: macos-14
|
29
29
|
continue-on-error: true
|
30
30
|
strategy:
|
31
31
|
matrix:
|
32
32
|
spec: ["objc_spec", "swift_spec", "cocoapods_spec"]
|
33
|
-
env:
|
34
|
-
DEVELOPER_DIR: /Applications/Xcode_15.0.app/Contents/Developer
|
35
33
|
steps:
|
36
|
-
- uses: actions/checkout@
|
34
|
+
- uses: actions/checkout@v4
|
37
35
|
with:
|
38
36
|
submodules: recursive
|
37
|
+
- uses: maxim-lobanov/setup-xcode@v1
|
38
|
+
with:
|
39
|
+
xcode-version: 15.3
|
39
40
|
- uses: ruby/setup-ruby@v1
|
40
41
|
with:
|
41
42
|
ruby-version: 3.2
|
data/.rubocop.yml
CHANGED
@@ -46,8 +46,12 @@ Lint/EmptyInPattern: # (new in 1.16)
|
|
46
46
|
Enabled: true
|
47
47
|
Lint/IncompatibleIoSelectWithFiberScheduler: # new in 1.21
|
48
48
|
Enabled: true
|
49
|
+
Lint/ItWithoutArgumentsInBlock: # new in 1.59
|
50
|
+
Enabled: true
|
49
51
|
Lint/LambdaWithoutLiteralBlock: # (new in 1.8)
|
50
52
|
Enabled: true
|
53
|
+
Lint/LiteralAssignmentInCondition: # new in 1.58
|
54
|
+
Enabled: true
|
51
55
|
Lint/MixedCaseRange: # new in 1.53
|
52
56
|
Enabled: true
|
53
57
|
Lint/NonAtomicFileOperation: # new in 1.31
|
@@ -136,6 +140,8 @@ Style/MagicCommentFormat: # new in 1.35
|
|
136
140
|
Enabled: true
|
137
141
|
Style/MapCompactWithConditionalBlock: # new in 1.30
|
138
142
|
Enabled: true
|
143
|
+
Style/MapIntoArray: # new in 1.63
|
144
|
+
Enabled: true
|
139
145
|
Style/MapToHash: # new in 1.24
|
140
146
|
Enabled: true
|
141
147
|
Style/MapToSet: # new in 1.42
|
@@ -194,8 +200,12 @@ Style/ReturnNilInPredicateMethodDefinition: # new in 1.53
|
|
194
200
|
Enabled: true
|
195
201
|
Style/SelectByRegexp: # new in 1.22
|
196
202
|
Enabled: true
|
203
|
+
Style/SingleLineDoEndBlock: # new in 1.57
|
204
|
+
Enabled: true
|
197
205
|
Style/StringChars: # (new in 1.12)
|
198
206
|
Enabled: true
|
207
|
+
Style/SuperWithArgsParentheses: # new in 1.58
|
208
|
+
Enabled: true
|
199
209
|
Style/SwapValues: # (new in 1.1)
|
200
210
|
Enabled: true
|
201
211
|
Style/YAMLFileRead: # new in 1.53
|
@@ -221,6 +231,9 @@ Metrics/ModuleLength:
|
|
221
231
|
Metrics/BlockLength:
|
222
232
|
Enabled: false
|
223
233
|
|
234
|
+
Metrics/ParameterLists:
|
235
|
+
CountKeywordArgs: false
|
236
|
+
|
224
237
|
Style/NumericPredicate:
|
225
238
|
Enabled: false
|
226
239
|
|
data/CHANGELOG.md
CHANGED
@@ -1,3 +1,43 @@
|
|
1
|
+
## 0.15.0
|
2
|
+
|
3
|
+
##### Breaking
|
4
|
+
|
5
|
+
* None.
|
6
|
+
|
7
|
+
##### Enhancements
|
8
|
+
|
9
|
+
* Update Javascript: typeahead.js 1.3.4, KaTeX 0.16.10
|
10
|
+
[John Fairhurst](https://github.com/johnfairh)
|
11
|
+
|
12
|
+
* Support Swift 5.10 with Swift Package Manager projects.
|
13
|
+
[John Fairhurst](https://github.com/johnfairh)
|
14
|
+
[#1381](https://github.com/realm/jazzy/issues/1381)
|
15
|
+
|
16
|
+
* Support documentation of multiple modules in a single website. Use
|
17
|
+
`--modules` or the config-file `modules` for more control. See the
|
18
|
+
README 'Documenting multiple modules' for more details.
|
19
|
+
[Argjira Mala](https://github.com/argjiramala-tomtom)
|
20
|
+
[Pedro Alcobia](https://github.com/PedroAlcobia-TomTom)
|
21
|
+
[John Fairhurst](https://github.com/johnfairh)
|
22
|
+
[#564](https://github.com/realm/jazzy/issues/564)
|
23
|
+
|
24
|
+
* Improve page breadcrumbs to include parent pages and indicate source module
|
25
|
+
of extensions from other modules.
|
26
|
+
[John Fairhurst](https://github.com/johnfairh)
|
27
|
+
|
28
|
+
* Add `--readme-title` and `--docset-title` to set the titles of the readme
|
29
|
+
docs page and the Dash docset independently of the module name.
|
30
|
+
[John Fairhurst](https://github.com/johnfairh)
|
31
|
+
|
32
|
+
* Support Swift 5.9 symbolgraph extension symbols.
|
33
|
+
[John Fairhurst](https://github.com/johnfairh)
|
34
|
+
[#1368](https://github.com/realm/jazzy/issues/1368)
|
35
|
+
|
36
|
+
##### Bug Fixes
|
37
|
+
|
38
|
+
* Fix incorrect activesupport usage.
|
39
|
+
[John Fairhurst](https://github.com/johnfairh)
|
40
|
+
|
1
41
|
## 0.14.4
|
2
42
|
|
3
43
|
##### Breaking
|
data/CONTRIBUTING.md
CHANGED
@@ -49,7 +49,7 @@ git push
|
|
49
49
|
You'll need push access to the integration specs repo to do this. You can
|
50
50
|
request access from one of the maintainers when filing your PR.
|
51
51
|
|
52
|
-
You must have Xcode
|
52
|
+
You must have Xcode 15.3 installed to build the integration specs.
|
53
53
|
|
54
54
|
## Making changes to SourceKitten
|
55
55
|
|
data/Gemfile.lock
CHANGED
@@ -9,7 +9,7 @@ GIT
|
|
9
9
|
PATH
|
10
10
|
remote: .
|
11
11
|
specs:
|
12
|
-
jazzy (0.
|
12
|
+
jazzy (0.15.0)
|
13
13
|
cocoapods (~> 1.5)
|
14
14
|
mustache (~> 1.1)
|
15
15
|
open4 (~> 1.3)
|
@@ -23,14 +23,21 @@ PATH
|
|
23
23
|
GEM
|
24
24
|
remote: https://rubygems.org/
|
25
25
|
specs:
|
26
|
-
CFPropertyList (3.0.
|
26
|
+
CFPropertyList (3.0.7)
|
27
|
+
base64
|
28
|
+
nkf
|
27
29
|
rexml
|
28
|
-
activesupport (7.
|
30
|
+
activesupport (7.1.3.2)
|
31
|
+
base64
|
32
|
+
bigdecimal
|
29
33
|
concurrent-ruby (~> 1.0, >= 1.0.2)
|
34
|
+
connection_pool (>= 2.2.5)
|
35
|
+
drb
|
30
36
|
i18n (>= 1.6, < 2)
|
31
37
|
minitest (>= 5.1)
|
38
|
+
mutex_m
|
32
39
|
tzinfo (~> 2.0)
|
33
|
-
addressable (2.8.
|
40
|
+
addressable (2.8.6)
|
34
41
|
public_suffix (>= 2.0.2, < 6.0)
|
35
42
|
algoliasearch (1.27.5)
|
36
43
|
httpclient (~> 2.8, >= 2.8.3)
|
@@ -38,18 +45,19 @@ GEM
|
|
38
45
|
ast (2.4.2)
|
39
46
|
atomos (0.1.3)
|
40
47
|
bacon (1.2.0)
|
41
|
-
base64 (0.
|
48
|
+
base64 (0.2.0)
|
49
|
+
bigdecimal (3.1.7)
|
42
50
|
claide (1.1.0)
|
43
51
|
claide-plugins (0.9.2)
|
44
52
|
cork
|
45
53
|
nap
|
46
54
|
open4 (~> 1.3)
|
47
|
-
cocoapods (1.
|
55
|
+
cocoapods (1.15.2)
|
48
56
|
addressable (~> 2.8)
|
49
57
|
claide (>= 1.0.2, < 2.0)
|
50
|
-
cocoapods-core (= 1.
|
58
|
+
cocoapods-core (= 1.15.2)
|
51
59
|
cocoapods-deintegrate (>= 1.0.3, < 2.0)
|
52
|
-
cocoapods-downloader (>= 1
|
60
|
+
cocoapods-downloader (>= 2.1, < 3.0)
|
53
61
|
cocoapods-plugins (>= 1.0.0, < 2.0)
|
54
62
|
cocoapods-search (>= 1.0.0, < 2.0)
|
55
63
|
cocoapods-trunk (>= 1.6.0, < 2.0)
|
@@ -61,8 +69,8 @@ GEM
|
|
61
69
|
molinillo (~> 0.8.0)
|
62
70
|
nap (~> 1.0)
|
63
71
|
ruby-macho (>= 2.3.0, < 3.0)
|
64
|
-
xcodeproj (>= 1.
|
65
|
-
cocoapods-core (1.
|
72
|
+
xcodeproj (>= 1.23.0, < 2.0)
|
73
|
+
cocoapods-core (1.15.2)
|
66
74
|
activesupport (>= 5.0, < 8)
|
67
75
|
addressable (~> 2.8)
|
68
76
|
algoliasearch (~> 1.0)
|
@@ -73,7 +81,7 @@ GEM
|
|
73
81
|
public_suffix (~> 4.0)
|
74
82
|
typhoeus (~> 1.0)
|
75
83
|
cocoapods-deintegrate (1.0.5)
|
76
|
-
cocoapods-downloader (1
|
84
|
+
cocoapods-downloader (2.1)
|
77
85
|
cocoapods-plugins (1.0.0)
|
78
86
|
nap
|
79
87
|
cocoapods-search (1.0.1)
|
@@ -82,12 +90,14 @@ GEM
|
|
82
90
|
netrc (~> 0.11)
|
83
91
|
cocoapods-try (1.2.0)
|
84
92
|
colored2 (3.1.2)
|
85
|
-
concurrent-ruby (1.2.
|
93
|
+
concurrent-ruby (1.2.3)
|
94
|
+
connection_pool (2.4.1)
|
86
95
|
cork (0.3.0)
|
87
96
|
colored2 (~> 3.1)
|
88
|
-
crack (0.
|
97
|
+
crack (1.0.0)
|
98
|
+
bigdecimal
|
89
99
|
rexml
|
90
|
-
danger (9.3
|
100
|
+
danger (9.4.3)
|
91
101
|
claide (~> 1.0)
|
92
102
|
claide-plugins (>= 0.9.2)
|
93
103
|
colored2 (~> 3.1)
|
@@ -98,82 +108,86 @@ GEM
|
|
98
108
|
kramdown (~> 2.3)
|
99
109
|
kramdown-parser-gfm (~> 1.0)
|
100
110
|
no_proxy_fix
|
101
|
-
octokit (
|
111
|
+
octokit (>= 4.0)
|
102
112
|
terminal-table (>= 1, < 4)
|
103
113
|
diffy (3.4.2)
|
114
|
+
drb (2.2.1)
|
104
115
|
escape (0.0.4)
|
105
116
|
ethon (0.16.0)
|
106
117
|
ffi (>= 1.15.0)
|
107
|
-
faraday (2.
|
108
|
-
|
109
|
-
|
110
|
-
ruby2_keywords (>= 0.0.4)
|
111
|
-
faraday-http-cache (2.5.0)
|
118
|
+
faraday (2.9.0)
|
119
|
+
faraday-net_http (>= 2.0, < 3.2)
|
120
|
+
faraday-http-cache (2.5.1)
|
112
121
|
faraday (>= 0.8)
|
113
|
-
faraday-net_http (3.0
|
114
|
-
|
122
|
+
faraday-net_http (3.1.0)
|
123
|
+
net-http
|
124
|
+
ffi (1.16.3)
|
115
125
|
fourflusher (2.3.1)
|
116
126
|
fuzzy_match (2.0.4)
|
117
127
|
gh_inspector (1.1.3)
|
118
|
-
git (1.
|
128
|
+
git (1.19.1)
|
119
129
|
addressable (~> 2.8)
|
120
130
|
rchardet (~> 1.8)
|
121
|
-
hashdiff (1.0
|
131
|
+
hashdiff (1.1.0)
|
122
132
|
httpclient (2.8.3)
|
123
|
-
i18n (1.14.
|
133
|
+
i18n (1.14.4)
|
124
134
|
concurrent-ruby (~> 1.0)
|
125
|
-
json (2.
|
135
|
+
json (2.7.2)
|
126
136
|
kramdown (2.4.0)
|
127
137
|
rexml
|
128
138
|
kramdown-parser-gfm (1.1.0)
|
129
139
|
kramdown (~> 2.0)
|
130
140
|
language_server-protocol (3.17.0.3)
|
131
141
|
liferaft (0.0.6)
|
132
|
-
mini_portile2 (2.8.
|
133
|
-
minitest (5.
|
134
|
-
mocha (2.
|
142
|
+
mini_portile2 (2.8.6)
|
143
|
+
minitest (5.22.3)
|
144
|
+
mocha (2.2.0)
|
135
145
|
ruby2_keywords (>= 0.0.5)
|
136
146
|
mocha-on-bacon (0.2.3)
|
137
147
|
mocha (>= 0.13.0)
|
138
148
|
molinillo (0.8.0)
|
139
149
|
mustache (1.1.1)
|
150
|
+
mutex_m (0.2.0)
|
140
151
|
nanaimo (0.3.0)
|
141
152
|
nap (1.1.0)
|
153
|
+
net-http (0.4.1)
|
154
|
+
uri
|
142
155
|
netrc (0.11.0)
|
156
|
+
nkf (0.2.0)
|
143
157
|
no_proxy_fix (0.1.2)
|
144
|
-
octokit (
|
158
|
+
octokit (8.1.0)
|
159
|
+
base64
|
145
160
|
faraday (>= 1, < 3)
|
146
161
|
sawyer (~> 0.9)
|
147
162
|
open4 (1.3.4)
|
148
|
-
parallel (1.
|
149
|
-
parser (3.
|
163
|
+
parallel (1.24.0)
|
164
|
+
parser (3.3.1.0)
|
150
165
|
ast (~> 2.4.1)
|
151
166
|
racc
|
152
167
|
prettybacon (0.0.2)
|
153
168
|
bacon (~> 1.2)
|
154
169
|
public_suffix (4.0.7)
|
155
|
-
racc (1.7.
|
170
|
+
racc (1.7.3)
|
156
171
|
rainbow (3.1.1)
|
157
|
-
rake (13.
|
172
|
+
rake (13.2.1)
|
158
173
|
rchardet (1.8.0)
|
159
174
|
redcarpet (3.6.0)
|
160
|
-
regexp_parser (2.
|
175
|
+
regexp_parser (2.9.0)
|
161
176
|
rexml (3.2.6)
|
162
|
-
rouge (4.1
|
163
|
-
rubocop (1.
|
164
|
-
base64 (~> 0.1.1)
|
177
|
+
rouge (4.2.1)
|
178
|
+
rubocop (1.63.4)
|
165
179
|
json (~> 2.3)
|
166
180
|
language_server-protocol (>= 3.17.0)
|
167
181
|
parallel (~> 1.10)
|
168
|
-
parser (>= 3.
|
182
|
+
parser (>= 3.3.0.2)
|
169
183
|
rainbow (>= 2.2.2, < 4.0)
|
170
184
|
regexp_parser (>= 1.8, < 3.0)
|
171
185
|
rexml (>= 3.2.5, < 4.0)
|
172
|
-
rubocop-ast (>= 1.
|
186
|
+
rubocop-ast (>= 1.31.1, < 2.0)
|
173
187
|
ruby-progressbar (~> 1.7)
|
174
188
|
unicode-display_width (>= 2.4.0, < 3.0)
|
175
|
-
rubocop-ast (1.
|
176
|
-
parser (>= 3.
|
189
|
+
rubocop-ast (1.31.3)
|
190
|
+
parser (>= 3.3.1.0)
|
177
191
|
ruby-macho (2.5.1)
|
178
192
|
ruby-progressbar (1.13.0)
|
179
193
|
ruby2_keywords (0.0.5)
|
@@ -182,22 +196,23 @@ GEM
|
|
182
196
|
sawyer (0.9.2)
|
183
197
|
addressable (>= 2.3.5)
|
184
198
|
faraday (>= 0.17.3, < 3)
|
185
|
-
sqlite3 (1.
|
199
|
+
sqlite3 (1.7.3)
|
186
200
|
mini_portile2 (~> 2.8.0)
|
187
201
|
terminal-table (3.0.2)
|
188
202
|
unicode-display_width (>= 1.1.1, < 3)
|
189
|
-
typhoeus (1.4.
|
203
|
+
typhoeus (1.4.1)
|
190
204
|
ethon (>= 0.9.0)
|
191
205
|
tzinfo (2.0.6)
|
192
206
|
concurrent-ruby (~> 1.0)
|
193
|
-
unicode-display_width (2.
|
194
|
-
|
207
|
+
unicode-display_width (2.5.0)
|
208
|
+
uri (0.13.0)
|
209
|
+
webmock (3.23.0)
|
195
210
|
addressable (>= 2.8.0)
|
196
211
|
crack (>= 0.3.2)
|
197
212
|
hashdiff (>= 0.4.0, < 2.0.0)
|
198
213
|
xcinvoke (0.3.0)
|
199
214
|
liferaft (~> 0.0.6)
|
200
|
-
xcodeproj (1.
|
215
|
+
xcodeproj (1.24.0)
|
201
216
|
CFPropertyList (>= 2.3.3, < 4.0)
|
202
217
|
atomos (~> 0.1.3)
|
203
218
|
claide (>= 1.0.2, < 2.0)
|
data/README.md
CHANGED
@@ -53,6 +53,9 @@ one you'd prefer. If this doesn't help, and you're using Xcode, then try passin
|
|
53
53
|
extra arguments to `xcodebuild`, for example
|
54
54
|
`jazzy --build-tool-arguments -scheme,MyScheme,-target,MyTarget`.
|
55
55
|
|
56
|
+
If you want to generate docs for several modules at once then see [Documenting multiple
|
57
|
+
modules](#documenting-multiple-modules).
|
58
|
+
|
56
59
|
You can set options for your project’s documentation in a configuration file,
|
57
60
|
`.jazzy.yaml` by default. For a detailed explanation and an exhaustive list of
|
58
61
|
all available options, run `jazzy --help config`.
|
@@ -85,6 +88,13 @@ Jazzy understands Apple's DocC-style links too, for example:
|
|
85
88
|
* \`\`\<doc:method(_:)-e873\>\`\` - a link to a specific overload of `method(_:)`.
|
86
89
|
Jazzy can't tell which overload you intend and links to the first one.
|
87
90
|
|
91
|
+
If your documentation is for multiple modules then symbol name resolution works
|
92
|
+
approximately as though all the modules have been imported: you can use \`TypeName\`
|
93
|
+
to refer to a top-level type in any of the modules, or \`ModuleName.TypeName\` to
|
94
|
+
be specific. If there is an ambiguity then you can use a leading slash to
|
95
|
+
indicate that the first part of the name should be read as a module name:
|
96
|
+
\`/ModuleName.TypeName\`.
|
97
|
+
|
88
98
|
### Math
|
89
99
|
|
90
100
|
Jazzy can render math equations written in LaTeX embedded in your markdown:
|
@@ -192,7 +202,7 @@ on troubleshooting.
|
|
192
202
|
|
193
203
|
### Mixed Objective-C / Swift
|
194
204
|
|
195
|
-
*This feature
|
205
|
+
*This feature has some rough edges.*
|
196
206
|
|
197
207
|
To generate documentation for a mixed Swift and Objective-C project you must first
|
198
208
|
generate two [SourceKitten][sourcekitten] files: one for Swift and one for Objective-C.
|
@@ -219,8 +229,6 @@ jazzy --module MyProject --sourcekitten-sourcefile swiftDoc.json,objcDoc.json
|
|
219
229
|
|
220
230
|
### Docs from `.swiftmodule`s or frameworks
|
221
231
|
|
222
|
-
*This feature is new: there may be crashes and mistakes. Reports welcome.*
|
223
|
-
|
224
232
|
Swift 5.3 added support for symbol graph generation from `.swiftmodule` files.
|
225
233
|
|
226
234
|
Jazzy can use this to generate API documentation. This is faster than using
|
@@ -274,6 +282,78 @@ See `swift symbolgraph-extract -help` for all the things you can pass via
|
|
274
282
|
`--build-tool-arguments`: if your module has dependencies then you may need
|
275
283
|
to add various search path options to let Swift load it.
|
276
284
|
|
285
|
+
### Documenting multiple modules
|
286
|
+
|
287
|
+
*This feature is new, bugs and feedback welcome*
|
288
|
+
|
289
|
+
Sometimes it's useful to document multiple modules together in the same site,
|
290
|
+
for example an app and its extensions, or an SDK that happens to be implemented
|
291
|
+
as several modules.
|
292
|
+
|
293
|
+
Jazzy can build docs for all these together and create a single site with
|
294
|
+
search, cross-module linking, and navigation.
|
295
|
+
|
296
|
+
#### Build configuration
|
297
|
+
|
298
|
+
If all the modules share the same build flags then the easiest way to do this
|
299
|
+
is with `--modules`, for example `jazzy --modules ModuleA,ModuleB,ModuleC`.
|
300
|
+
|
301
|
+
If your modules have different build flags then you have to use the config file.
|
302
|
+
For example:
|
303
|
+
```yaml
|
304
|
+
modules:
|
305
|
+
- module: ModuleA
|
306
|
+
- module: ModuleB
|
307
|
+
build_tool_arguments:
|
308
|
+
- -scheme
|
309
|
+
- SpecialScheme
|
310
|
+
- -target
|
311
|
+
- ModuleB
|
312
|
+
source_directory: ModuleBProject
|
313
|
+
- module: ModuleC
|
314
|
+
objc: true
|
315
|
+
umbrella_header: ModuleC/ModuleC.h
|
316
|
+
framework_root: ModuleC
|
317
|
+
sdk: appletvsimulator
|
318
|
+
- module: ModuleD
|
319
|
+
sourcekitten_sourcefile: [ModuleD1.json, ModuleD2.json]
|
320
|
+
```
|
321
|
+
This describes a four-module project of which one is 'normal', one requires
|
322
|
+
special Xcode treatment, one is Objective-C, and one has prebuilt SourceKitten
|
323
|
+
JSON.
|
324
|
+
|
325
|
+
Per-module options set at the top level are inherited by each module unless
|
326
|
+
also set locally -- but you can't set both `--module` and `--modules`.
|
327
|
+
|
328
|
+
Jazzy doesn't support `--podspec` mode in conjunction with the multiple
|
329
|
+
modules feature.
|
330
|
+
|
331
|
+
#### Presentation
|
332
|
+
|
333
|
+
The `--merge-modules` flag controls how declarations from multiple modules
|
334
|
+
are arranged into categories.
|
335
|
+
|
336
|
+
The default of `all` has Jazzy combine declarations from the modules so there
|
337
|
+
is one category of classes, one of structures, and so on. To the user this means
|
338
|
+
they do not worry about which module exports a particular type, although that
|
339
|
+
information remains available in the type's page.
|
340
|
+
|
341
|
+
Setting `--merge-modules none` changes this so each module is a top-level
|
342
|
+
category, with the module's symbols listed under it.
|
343
|
+
|
344
|
+
Setting `--merge-modules extensions` is like `none` except cross-module
|
345
|
+
extensions are shown as part of their extended type. For example if `ModuleA`
|
346
|
+
extends `ModuleB.SomeType` then those extension members from `ModuleA` are shown
|
347
|
+
on the `ModuleB.SomeType` page along with the rest of `SomeType`.
|
348
|
+
|
349
|
+
You can use `--documentation` to include guides, `custom_categories` to customize
|
350
|
+
the layout with types from whichever modules you want, and `--abstract` to add
|
351
|
+
additional markdown content to the per-module category pages.
|
352
|
+
|
353
|
+
Use the `--title`, `--readme-title`, and `--docset-title` flags to control the
|
354
|
+
top-level names of your documentation. Without these, Jazzy uses the name of one
|
355
|
+
of the modules being documented.
|
356
|
+
|
277
357
|
### Themes
|
278
358
|
|
279
359
|
Three themes are provided with jazzy: `apple` (default), `fullwidth` and `jony`.
|
@@ -303,6 +383,10 @@ There are a few limitations:
|
|
303
383
|
- File names must be unique from source files.
|
304
384
|
- Readme should be specified separately using the `readme` option.
|
305
385
|
|
386
|
+
You can link to a guide from other guides or doc comments using the name of the page
|
387
|
+
as it appears in the site. For example, to link to the guide generated from a file
|
388
|
+
called `My Guide.md` you would write \`My Guide\`.
|
389
|
+
|
306
390
|
### Section description abstracts
|
307
391
|
|
308
392
|
| Description | Command |
|
@@ -399,7 +483,7 @@ alphabetical by symbol name and USR; the order is stable for the same input.
|
|
399
483
|
|
400
484
|
Jazzy does not normally create separate web pages for declarations that do not
|
401
485
|
have any members -- instead they are entirely nested into their parent page. Use
|
402
|
-
the `--separate-global-declarations` flag to change this and
|
486
|
+
the `--separate-global-declarations` flag to change this and create pages for
|
403
487
|
these empty types.
|
404
488
|
|
405
489
|
### Choosing the Swift language version
|
@@ -423,6 +507,24 @@ jazzy --swift-version 5.7
|
|
423
507
|
DEVELOPER_DIR=/Applications/Xcode_14.app/Contents/Developer jazzy
|
424
508
|
```
|
425
509
|
|
510
|
+
### Dash Docset Support
|
511
|
+
|
512
|
+
As well as the browsable HTML documentation, Jazzy creates a _docset_ for use
|
513
|
+
with the [Dash][dash] app.
|
514
|
+
|
515
|
+
By default the docset is created at `docs/docsets/ModuleName.tgz`. Use
|
516
|
+
`--docset-path` to create it somewhere else; use `--docset-title` to change
|
517
|
+
the docset's title.
|
518
|
+
|
519
|
+
Use `--docset-playground-url` and `--docset-icon` to further customize the
|
520
|
+
docset.
|
521
|
+
|
522
|
+
If you set both `--root-url` to be the (https://) URL where you plan to deploy
|
523
|
+
your documentation and `--version` to give your documentation a version number
|
524
|
+
then Jazzy also creates a docset feed XML file and includes an "Install in Dash"
|
525
|
+
button on the site. This lets users who are browsing your documentation on the
|
526
|
+
web install and start using the docs in Dash locally.
|
527
|
+
|
426
528
|
## Linux
|
427
529
|
|
428
530
|
Jazzy uses [SourceKitten][sourcekitten] to communicate with the Swift build
|
@@ -469,7 +571,7 @@ See [this document](ObjectiveC.md).
|
|
469
571
|
|
470
572
|
**Missing docset**
|
471
573
|
|
472
|
-
Jazzy only builds a docset when you set the `--module` flag.
|
574
|
+
Jazzy only builds a docset when you set the `--module` or `--modules` flag.
|
473
575
|
|
474
576
|
**Unable to pass --build-tool-arguments containing commas**
|
475
577
|
|
@@ -495,6 +597,13 @@ Users [have reported](https://github.com/realm/jazzy/issues/1012) that error
|
|
495
597
|
messages about symbols lacking USRs can be fixed by unsetting
|
496
598
|
`LLVM_TARGET_TRIPLE_SUFFIX` as part of the run script.
|
497
599
|
|
600
|
+
**Warnings about matches and leftovers when using globs and wildcards**
|
601
|
+
|
602
|
+
Some flags such as `--include` and `--documentation` support '*' characters as
|
603
|
+
wildcards. If you are using the CLI then you must make sure that your shell
|
604
|
+
does not itself try to interpret them, for example by quoting the token: use
|
605
|
+
`jazzy --documentation '*.md'` instead of `jazzy --documentation *.md`.
|
606
|
+
|
498
607
|
### Installation Problems
|
499
608
|
|
500
609
|
**Can't find header files / clang**
|
@@ -569,3 +678,4 @@ read [our blog](https://realm.io/news) or say hi on twitter
|
|
569
678
|
[bundler]: https://rubygems.org/gems/bundler
|
570
679
|
[mustache]: https://mustache.github.io "Mustache"
|
571
680
|
[spm]: https://swift.org/package-manager/ "Swift Package Manager"
|
681
|
+
[dash]: https://kapeli.com/dash/ "Dash"
|
data/bin/sourcekitten
CHANGED
Binary file
|
data/js/package-lock.json
CHANGED
@@ -24,9 +24,9 @@
|
|
24
24
|
}
|
25
25
|
},
|
26
26
|
"node_modules/corejs-typeahead": {
|
27
|
-
"version": "1.3.
|
28
|
-
"resolved": "https://registry.npmjs.org/corejs-typeahead/-/corejs-typeahead-1.3.
|
29
|
-
"integrity": "sha512-
|
27
|
+
"version": "1.3.4",
|
28
|
+
"resolved": "https://registry.npmjs.org/corejs-typeahead/-/corejs-typeahead-1.3.4.tgz",
|
29
|
+
"integrity": "sha512-4SAc1UWszc05IyG9te1JHSeLas5WUWKmKAB8m9E6AAmHCpYhdSaySkblVSIUwQG2FR5uAsaeHbKM+pkEP7SiNw==",
|
30
30
|
"dependencies": {
|
31
31
|
"jquery": ">=1.11"
|
32
32
|
}
|
@@ -37,9 +37,9 @@
|
|
37
37
|
"integrity": "sha512-m4avr8yL8kmFN8psrbFFFmB/If14iN5o9nw/NgnnM+kybDJpRsAynV2BsfpTYrTRysYUdADVD7CkUUizgkpLfg=="
|
38
38
|
},
|
39
39
|
"node_modules/katex": {
|
40
|
-
"version": "0.16.
|
41
|
-
"resolved": "https://registry.npmjs.org/katex/-/katex-0.16.
|
42
|
-
"integrity": "sha512-
|
40
|
+
"version": "0.16.10",
|
41
|
+
"resolved": "https://registry.npmjs.org/katex/-/katex-0.16.10.tgz",
|
42
|
+
"integrity": "sha512-ZiqaC04tp2O5utMsl2TEZTXxa6WSC4yo0fv5ML++D3QZv/vx2Mct0mTlRx3O+uUkjfuAgOkzsCmq5MiUEsDDdA==",
|
43
43
|
"funding": [
|
44
44
|
"https://opencollective.com/katex",
|
45
45
|
"https://github.com/sponsors/katex"
|