jazzy 0.14.4 → 0.15.1
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 +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"
|