jazzy 0.14.4 → 0.15.1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/.github/workflows/Tests.yml +6 -5
- data/.rubocop.yml +19 -0
- data/CHANGELOG.md +56 -0
- data/CONTRIBUTING.md +1 -1
- data/Gemfile.lock +66 -49
- data/README.md +115 -5
- data/bin/sourcekitten +0 -0
- data/jazzy.gemspec +1 -1
- 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 +232 -236
- 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 +16 -7
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: 233b49769d27b199b20651cff4041041fda0c9506945290fea84937ee5f1723f
|
4
|
+
data.tar.gz: 55148a0bff106913b60dd295851d069a8aa344a21c2b52e3453d1bbeebd2a8ad
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: f093b513515728c93ffce07528fe6042d05063b8b9b78e4283f89f9e41632a06509434bc3f533f2b4e1d9f30619cde090acff726a1463ea61669091f56734f41
|
7
|
+
data.tar.gz: 36ba08e16c04d207568ce01f1e864bee4d495197cdf14bbc643d714e3ea85aeff2c9c102e4baa7122916f49dbf2d3e77dcf59ecebfd4a9c1839b5eb9bf18e08d
|
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
@@ -10,6 +10,8 @@ AllCops:
|
|
10
10
|
|
11
11
|
#- Pending Cops as of 1.56.3 ---------------------------------------------#
|
12
12
|
|
13
|
+
|
14
|
+
|
13
15
|
Gemspec/DeprecatedAttributeAssignment: # new in 1.30
|
14
16
|
Enabled: true
|
15
17
|
Gemspec/DevelopmentDependencies: # new in 1.44
|
@@ -46,8 +48,12 @@ Lint/EmptyInPattern: # (new in 1.16)
|
|
46
48
|
Enabled: true
|
47
49
|
Lint/IncompatibleIoSelectWithFiberScheduler: # new in 1.21
|
48
50
|
Enabled: true
|
51
|
+
Lint/ItWithoutArgumentsInBlock: # new in 1.59
|
52
|
+
Enabled: true
|
49
53
|
Lint/LambdaWithoutLiteralBlock: # (new in 1.8)
|
50
54
|
Enabled: true
|
55
|
+
Lint/LiteralAssignmentInCondition: # new in 1.58
|
56
|
+
Enabled: true
|
51
57
|
Lint/MixedCaseRange: # new in 1.53
|
52
58
|
Enabled: true
|
53
59
|
Lint/NonAtomicFileOperation: # new in 1.31
|
@@ -136,6 +142,8 @@ Style/MagicCommentFormat: # new in 1.35
|
|
136
142
|
Enabled: true
|
137
143
|
Style/MapCompactWithConditionalBlock: # new in 1.30
|
138
144
|
Enabled: true
|
145
|
+
Style/MapIntoArray: # new in 1.63
|
146
|
+
Enabled: true
|
139
147
|
Style/MapToHash: # new in 1.24
|
140
148
|
Enabled: true
|
141
149
|
Style/MapToSet: # new in 1.42
|
@@ -194,8 +202,16 @@ Style/ReturnNilInPredicateMethodDefinition: # new in 1.53
|
|
194
202
|
Enabled: true
|
195
203
|
Style/SelectByRegexp: # new in 1.22
|
196
204
|
Enabled: true
|
205
|
+
Style/SendWithLiteralMethodName: # new in 1.64
|
206
|
+
Enabled: true
|
207
|
+
Style/SingleLineDoEndBlock: # new in 1.57
|
208
|
+
Enabled: true
|
197
209
|
Style/StringChars: # (new in 1.12)
|
198
210
|
Enabled: true
|
211
|
+
Style/SuperArguments: # new in 1.64
|
212
|
+
Enabled: true
|
213
|
+
Style/SuperWithArgsParentheses: # new in 1.58
|
214
|
+
Enabled: true
|
199
215
|
Style/SwapValues: # (new in 1.1)
|
200
216
|
Enabled: true
|
201
217
|
Style/YAMLFileRead: # new in 1.53
|
@@ -221,6 +237,9 @@ Metrics/ModuleLength:
|
|
221
237
|
Metrics/BlockLength:
|
222
238
|
Enabled: false
|
223
239
|
|
240
|
+
Metrics/ParameterLists:
|
241
|
+
CountKeywordArgs: false
|
242
|
+
|
224
243
|
Style/NumericPredicate:
|
225
244
|
Enabled: false
|
226
245
|
|
data/CHANGELOG.md
CHANGED
@@ -1,3 +1,59 @@
|
|
1
|
+
## 0.15.1
|
2
|
+
|
3
|
+
##### Breaking
|
4
|
+
|
5
|
+
* None.
|
6
|
+
|
7
|
+
##### Enhancements
|
8
|
+
|
9
|
+
* None.
|
10
|
+
|
11
|
+
##### Bug Fixes
|
12
|
+
|
13
|
+
* Restore compatibility with Ruby 2.6
|
14
|
+
[John Fairhurst](https://github.com/johnfairh)
|
15
|
+
[#1388](https://github.com/realm/jazzy/issues/1388)
|
16
|
+
|
17
|
+
## 0.15.0
|
18
|
+
|
19
|
+
##### Breaking
|
20
|
+
|
21
|
+
* None.
|
22
|
+
|
23
|
+
##### Enhancements
|
24
|
+
|
25
|
+
* Update Javascript: typeahead.js 1.3.4, KaTeX 0.16.10
|
26
|
+
[John Fairhurst](https://github.com/johnfairh)
|
27
|
+
|
28
|
+
* Support Swift 5.10 with Swift Package Manager projects.
|
29
|
+
[John Fairhurst](https://github.com/johnfairh)
|
30
|
+
[#1381](https://github.com/realm/jazzy/issues/1381)
|
31
|
+
|
32
|
+
* Support documentation of multiple modules in a single website. Use
|
33
|
+
`--modules` or the config-file `modules` for more control. See the
|
34
|
+
README 'Documenting multiple modules' for more details.
|
35
|
+
[Argjira Mala](https://github.com/argjiramala-tomtom)
|
36
|
+
[Pedro Alcobia](https://github.com/PedroAlcobia-TomTom)
|
37
|
+
[John Fairhurst](https://github.com/johnfairh)
|
38
|
+
[#564](https://github.com/realm/jazzy/issues/564)
|
39
|
+
|
40
|
+
* Improve page breadcrumbs to include parent pages and indicate source module
|
41
|
+
of extensions from other modules.
|
42
|
+
[John Fairhurst](https://github.com/johnfairh)
|
43
|
+
|
44
|
+
* Add `--readme-title` and `--docset-title` to set the titles of the readme
|
45
|
+
docs page and the Dash docset independently of the module name.
|
46
|
+
[John Fairhurst](https://github.com/johnfairh)
|
47
|
+
|
48
|
+
* Support Swift 5.9 symbolgraph extension symbols.
|
49
|
+
[John Fairhurst](https://github.com/johnfairh)
|
50
|
+
[#1368](https://github.com/realm/jazzy/issues/1368)
|
51
|
+
|
52
|
+
##### Bug Fixes
|
53
|
+
|
54
|
+
* Fix incorrect activesupport usage.
|
55
|
+
[John Fairhurst](https://github.com/johnfairh)
|
56
|
+
|
1
57
|
## 0.14.4
|
2
58
|
|
3
59
|
##### 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,12 +9,12 @@ GIT
|
|
9
9
|
PATH
|
10
10
|
remote: .
|
11
11
|
specs:
|
12
|
-
jazzy (0.
|
12
|
+
jazzy (0.15.1)
|
13
13
|
cocoapods (~> 1.5)
|
14
14
|
mustache (~> 1.1)
|
15
15
|
open4 (~> 1.3)
|
16
16
|
redcarpet (~> 3.4)
|
17
|
-
rexml (
|
17
|
+
rexml (>= 3.2.7, < 4.0)
|
18
18
|
rouge (>= 2.0.6, < 5.0)
|
19
19
|
sassc (~> 2.1)
|
20
20
|
sqlite3 (~> 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.4)
|
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.8)
|
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.
|
93
|
+
concurrent-ruby (1.3.2)
|
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,87 @@ 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.1)
|
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.17.0)
|
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.5)
|
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.7)
|
143
|
+
minitest (5.23.1)
|
144
|
+
mocha (2.3.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.2.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.
|
170
|
+
racc (1.8.0)
|
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.
|
161
|
-
rexml (3.2.
|
162
|
-
|
163
|
-
|
164
|
-
|
175
|
+
regexp_parser (2.9.2)
|
176
|
+
rexml (3.2.8)
|
177
|
+
strscan (>= 3.0.9)
|
178
|
+
rouge (4.2.1)
|
179
|
+
rubocop (1.64.1)
|
165
180
|
json (~> 2.3)
|
166
181
|
language_server-protocol (>= 3.17.0)
|
167
182
|
parallel (~> 1.10)
|
168
|
-
parser (>= 3.
|
183
|
+
parser (>= 3.3.0.2)
|
169
184
|
rainbow (>= 2.2.2, < 4.0)
|
170
185
|
regexp_parser (>= 1.8, < 3.0)
|
171
186
|
rexml (>= 3.2.5, < 4.0)
|
172
|
-
rubocop-ast (>= 1.
|
187
|
+
rubocop-ast (>= 1.31.1, < 2.0)
|
173
188
|
ruby-progressbar (~> 1.7)
|
174
189
|
unicode-display_width (>= 2.4.0, < 3.0)
|
175
|
-
rubocop-ast (1.
|
176
|
-
parser (>= 3.
|
190
|
+
rubocop-ast (1.31.3)
|
191
|
+
parser (>= 3.3.1.0)
|
177
192
|
ruby-macho (2.5.1)
|
178
193
|
ruby-progressbar (1.13.0)
|
179
194
|
ruby2_keywords (0.0.5)
|
@@ -182,22 +197,24 @@ GEM
|
|
182
197
|
sawyer (0.9.2)
|
183
198
|
addressable (>= 2.3.5)
|
184
199
|
faraday (>= 0.17.3, < 3)
|
185
|
-
sqlite3 (1.
|
200
|
+
sqlite3 (1.7.3)
|
186
201
|
mini_portile2 (~> 2.8.0)
|
202
|
+
strscan (3.1.0)
|
187
203
|
terminal-table (3.0.2)
|
188
204
|
unicode-display_width (>= 1.1.1, < 3)
|
189
|
-
typhoeus (1.4.
|
205
|
+
typhoeus (1.4.1)
|
190
206
|
ethon (>= 0.9.0)
|
191
207
|
tzinfo (2.0.6)
|
192
208
|
concurrent-ruby (~> 1.0)
|
193
|
-
unicode-display_width (2.
|
194
|
-
|
209
|
+
unicode-display_width (2.5.0)
|
210
|
+
uri (0.13.0)
|
211
|
+
webmock (3.23.1)
|
195
212
|
addressable (>= 2.8.0)
|
196
213
|
crack (>= 0.3.2)
|
197
214
|
hashdiff (>= 0.4.0, < 2.0.0)
|
198
215
|
xcinvoke (0.3.0)
|
199
216
|
liferaft (~> 0.0.6)
|
200
|
-
xcodeproj (1.
|
217
|
+
xcodeproj (1.24.0)
|
201
218
|
CFPropertyList (>= 2.3.3, < 4.0)
|
202
219
|
atomos (~> 0.1.3)
|
203
220
|
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/jazzy.gemspec
CHANGED
@@ -22,7 +22,7 @@ Gem::Specification.new do |spec|
|
|
22
22
|
spec.add_runtime_dependency 'mustache', '~> 1.1'
|
23
23
|
spec.add_runtime_dependency 'open4', '~> 1.3'
|
24
24
|
spec.add_runtime_dependency 'redcarpet', '~> 3.4'
|
25
|
-
spec.add_runtime_dependency 'rexml', '
|
25
|
+
spec.add_runtime_dependency 'rexml', ['>= 3.2.7', '< 4.0']
|
26
26
|
spec.add_runtime_dependency 'rouge', ['>= 2.0.6', '< 5.0']
|
27
27
|
spec.add_runtime_dependency 'sassc', '~> 2.1'
|
28
28
|
spec.add_runtime_dependency 'sqlite3', '~> 1.3'
|
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"
|