jazzy 0.14.4 → 0.15.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (42) hide show
  1. checksums.yaml +4 -4
  2. data/.github/workflows/Tests.yml +6 -5
  3. data/.rubocop.yml +13 -0
  4. data/CHANGELOG.md +40 -0
  5. data/CONTRIBUTING.md +1 -1
  6. data/Gemfile.lock +62 -47
  7. data/README.md +115 -5
  8. data/bin/sourcekitten +0 -0
  9. data/js/package-lock.json +6 -6
  10. data/lib/jazzy/config.rb +156 -24
  11. data/lib/jazzy/doc.rb +2 -2
  12. data/lib/jazzy/doc_builder.rb +55 -29
  13. data/lib/jazzy/doc_index.rb +185 -0
  14. data/lib/jazzy/docset_builder/info_plist.mustache +1 -1
  15. data/lib/jazzy/docset_builder.rb +44 -13
  16. data/lib/jazzy/extensions/katex/css/katex.min.css +1 -1
  17. data/lib/jazzy/extensions/katex/js/katex.min.js +1 -1
  18. data/lib/jazzy/gem_version.rb +1 -1
  19. data/lib/jazzy/grouper.rb +130 -0
  20. data/lib/jazzy/podspec_documenter.rb +1 -1
  21. data/lib/jazzy/source_declaration/type.rb +10 -2
  22. data/lib/jazzy/source_declaration.rb +69 -8
  23. data/lib/jazzy/source_document.rb +5 -1
  24. data/lib/jazzy/source_module.rb +13 -11
  25. data/lib/jazzy/sourcekitten.rb +231 -237
  26. data/lib/jazzy/symbol_graph/ext_key.rb +37 -0
  27. data/lib/jazzy/symbol_graph/ext_node.rb +23 -6
  28. data/lib/jazzy/symbol_graph/graph.rb +31 -19
  29. data/lib/jazzy/symbol_graph/relationship.rb +21 -3
  30. data/lib/jazzy/symbol_graph/sym_node.rb +10 -22
  31. data/lib/jazzy/symbol_graph/symbol.rb +28 -0
  32. data/lib/jazzy/symbol_graph.rb +19 -16
  33. data/lib/jazzy/themes/apple/assets/css/jazzy.css.scss +10 -7
  34. data/lib/jazzy/themes/apple/assets/js/typeahead.jquery.js +3 -2
  35. data/lib/jazzy/themes/apple/templates/doc.mustache +8 -1
  36. data/lib/jazzy/themes/fullwidth/assets/css/jazzy.css.scss +5 -5
  37. data/lib/jazzy/themes/fullwidth/assets/js/typeahead.jquery.js +3 -2
  38. data/lib/jazzy/themes/fullwidth/templates/doc.mustache +8 -1
  39. data/lib/jazzy/themes/jony/assets/css/jazzy.css.scss +6 -5
  40. data/lib/jazzy/themes/jony/templates/doc.mustache +9 -2
  41. data/spec/integration_spec.rb +8 -1
  42. metadata +5 -2
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 46b23a5fd216d0d68d6d48b094669c92fbbccdca52e5a7923a11429a9bdca958
4
- data.tar.gz: 3d16963bbb5e8dac679125d548ba3652e45bd42354b151c9886006f2fa86d82c
3
+ metadata.gz: a4e56611ebbc1fd23b15eb87740d56ca89523b6d98a9d1c7a8219fdc62e8b3d4
4
+ data.tar.gz: d3ffb914f1df703944287fa69b00e4c68b734076eeb825a2ab59857f27d28f6d
5
5
  SHA512:
6
- metadata.gz: 9cb4e55db01ae8d541128f97bce1470f5c5b133e4925c24cacb3c234c242ed7978c23f94fb16f35e92455696ea9b012c914e7db4019e001de68eebcb016f1dc7
7
- data.tar.gz: 0aa0c110530795c1c30a7b4c6f3ca4378fb9c40f5740c48ef3c04a6fb14e52f5daf39f1be0335d351902e94b23034b0b7ad29a01ae56ae262303245b44e63469
6
+ metadata.gz: c3418c7fe4eb7f9d1a83316fc3df22d0e7c87f42487f74ab62cc94e3b47e6e6c644327ef59ea5e4abae9a074b8adcf63da3c757df421a888220cdd4b039c6e5c
7
+ data.tar.gz: 2c28f8a6b6b8f4537cf35b30bfb89690ac5efd9b492a420b1bd1bb7184e8a665c91ae6ca31e473cce386bee30c1001cc4d90900a5b914b6da0aa6cc8072668e7
@@ -10,7 +10,7 @@ jobs:
10
10
  danger_and_rubocop:
11
11
  runs-on: ubuntu-latest
12
12
  steps:
13
- - uses: actions/checkout@v3
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-13
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@v3
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 14 installed to build the integration specs.
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.14.4)
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.6)
26
+ CFPropertyList (3.0.7)
27
+ base64
28
+ nkf
27
29
  rexml
28
- activesupport (7.0.8)
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.5)
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.1.1)
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.12.1)
55
+ cocoapods (1.15.2)
48
56
  addressable (~> 2.8)
49
57
  claide (>= 1.0.2, < 2.0)
50
- cocoapods-core (= 1.12.1)
58
+ cocoapods-core (= 1.15.2)
51
59
  cocoapods-deintegrate (>= 1.0.3, < 2.0)
52
- cocoapods-downloader (>= 1.6.0, < 2.0)
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.21.0, < 2.0)
65
- cocoapods-core (1.12.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.6.3)
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.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.4.5)
97
+ crack (1.0.0)
98
+ bigdecimal
89
99
  rexml
90
- danger (9.3.1)
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 (~> 6.0)
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.7.11)
108
- base64
109
- faraday-net_http (>= 2.0, < 3.1)
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.2)
114
- ffi (1.15.5)
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.18.0)
128
+ git (1.19.1)
119
129
  addressable (~> 2.8)
120
130
  rchardet (~> 1.8)
121
- hashdiff (1.0.1)
131
+ hashdiff (1.1.0)
122
132
  httpclient (2.8.3)
123
- i18n (1.14.1)
133
+ i18n (1.14.4)
124
134
  concurrent-ruby (~> 1.0)
125
- json (2.6.3)
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.4)
133
- minitest (5.20.0)
134
- mocha (2.1.0)
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 (6.1.1)
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.23.0)
149
- parser (3.2.2.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.1)
170
+ racc (1.7.3)
156
171
  rainbow (3.1.1)
157
- rake (13.0.6)
172
+ rake (13.2.1)
158
173
  rchardet (1.8.0)
159
174
  redcarpet (3.6.0)
160
- regexp_parser (2.8.1)
175
+ regexp_parser (2.9.0)
161
176
  rexml (3.2.6)
162
- rouge (4.1.3)
163
- rubocop (1.56.3)
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.2.2.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.28.1, < 2.0)
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.29.0)
176
- parser (>= 3.2.1.0)
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.6.6)
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.0)
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.4.2)
194
- webmock (3.19.1)
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.22.0)
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 is new and has some rough edges.*
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 create pages for
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.3",
28
- "resolved": "https://registry.npmjs.org/corejs-typeahead/-/corejs-typeahead-1.3.3.tgz",
29
- "integrity": "sha512-i+WiSdYiB4QiWTlx9kbn/Nk3zvG/FT/cj8EgBlSkEvQB1doJKb61ix0i6jxe4Y8znvfM8g2nkSGglhsF/cWFAA==",
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.8",
41
- "resolved": "https://registry.npmjs.org/katex/-/katex-0.16.8.tgz",
42
- "integrity": "sha512-ftuDnJbcbOckGY11OO+zg3OofESlbR5DRl2cmN8HeWeeFIV7wTXvAOx8kEjZjobhA+9wh2fbKeO6cdcA9Mnovg==",
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"