jazzy 0.14.0 → 0.14.3

Sign up to get free protection for your applications and to get access to all the features.
Files changed (105) hide show
  1. checksums.yaml +4 -4
  2. data/.github/workflows/Tests.yml +5 -5
  3. data/.rubocop.yml +62 -2
  4. data/CHANGELOG.md +75 -0
  5. data/CONTRIBUTING.md +1 -1
  6. data/Gemfile.lock +76 -66
  7. data/ObjectiveC.md +208 -0
  8. data/README.md +42 -24
  9. data/Rakefile +5 -3
  10. data/bin/sourcekitten +0 -0
  11. data/jazzy.gemspec +2 -1
  12. data/js/package-lock.json +61 -12
  13. data/lib/jazzy/config.rb +54 -35
  14. data/lib/jazzy/doc_builder.rb +9 -2
  15. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_AMS-Regular.ttf +0 -0
  16. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_AMS-Regular.woff +0 -0
  17. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_AMS-Regular.woff2 +0 -0
  18. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Caligraphic-Bold.ttf +0 -0
  19. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Caligraphic-Bold.woff +0 -0
  20. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Caligraphic-Bold.woff2 +0 -0
  21. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Caligraphic-Regular.ttf +0 -0
  22. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Caligraphic-Regular.woff +0 -0
  23. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Caligraphic-Regular.woff2 +0 -0
  24. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Fraktur-Bold.ttf +0 -0
  25. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Fraktur-Bold.woff +0 -0
  26. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Fraktur-Bold.woff2 +0 -0
  27. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Fraktur-Regular.ttf +0 -0
  28. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Fraktur-Regular.woff +0 -0
  29. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Fraktur-Regular.woff2 +0 -0
  30. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-Bold.ttf +0 -0
  31. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-Bold.woff +0 -0
  32. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-Bold.woff2 +0 -0
  33. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-BoldItalic.ttf +0 -0
  34. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-BoldItalic.woff +0 -0
  35. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-BoldItalic.woff2 +0 -0
  36. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-Italic.ttf +0 -0
  37. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-Italic.woff +0 -0
  38. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-Italic.woff2 +0 -0
  39. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-Regular.ttf +0 -0
  40. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-Regular.woff +0 -0
  41. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-Regular.woff2 +0 -0
  42. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Math-BoldItalic.ttf +0 -0
  43. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Math-BoldItalic.woff +0 -0
  44. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Math-BoldItalic.woff2 +0 -0
  45. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Math-Italic.ttf +0 -0
  46. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Math-Italic.woff +0 -0
  47. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Math-Italic.woff2 +0 -0
  48. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_SansSerif-Bold.ttf +0 -0
  49. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_SansSerif-Bold.woff +0 -0
  50. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_SansSerif-Bold.woff2 +0 -0
  51. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_SansSerif-Italic.ttf +0 -0
  52. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_SansSerif-Italic.woff +0 -0
  53. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_SansSerif-Italic.woff2 +0 -0
  54. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_SansSerif-Regular.ttf +0 -0
  55. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_SansSerif-Regular.woff +0 -0
  56. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_SansSerif-Regular.woff2 +0 -0
  57. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Script-Regular.ttf +0 -0
  58. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Script-Regular.woff +0 -0
  59. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Script-Regular.woff2 +0 -0
  60. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size1-Regular.ttf +0 -0
  61. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size1-Regular.woff +0 -0
  62. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size1-Regular.woff2 +0 -0
  63. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size2-Regular.ttf +0 -0
  64. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size2-Regular.woff +0 -0
  65. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size2-Regular.woff2 +0 -0
  66. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size3-Regular.ttf +0 -0
  67. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size3-Regular.woff +0 -0
  68. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size3-Regular.woff2 +0 -0
  69. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size4-Regular.ttf +0 -0
  70. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size4-Regular.woff +0 -0
  71. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size4-Regular.woff2 +0 -0
  72. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Typewriter-Regular.ttf +0 -0
  73. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Typewriter-Regular.woff +0 -0
  74. data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Typewriter-Regular.woff2 +0 -0
  75. data/lib/jazzy/extensions/katex/css/katex.min.css +1 -1
  76. data/lib/jazzy/extensions/katex/js/katex.min.js +1 -1
  77. data/lib/jazzy/gem_version.rb +1 -1
  78. data/lib/jazzy/jazzy_markdown.rb +13 -3
  79. data/lib/jazzy/search_builder.rb +3 -5
  80. data/lib/jazzy/source_declaration/type.rb +26 -2
  81. data/lib/jazzy/source_declaration.rb +13 -2
  82. data/lib/jazzy/sourcekitten.rb +58 -10
  83. data/lib/jazzy/stats.rb +11 -2
  84. data/lib/jazzy/symbol_graph/graph.rb +7 -2
  85. data/lib/jazzy/symbol_graph/relationship.rb +6 -0
  86. data/lib/jazzy/symbol_graph/sym_node.rb +14 -1
  87. data/lib/jazzy/symbol_graph/symbol.rb +36 -10
  88. data/lib/jazzy/symbol_graph.rb +30 -19
  89. data/lib/jazzy/themes/apple/assets/js/jquery.min.js +2 -2
  90. data/lib/jazzy/themes/apple/templates/doc.mustache +1 -2
  91. data/lib/jazzy/themes/apple/templates/footer.mustache +1 -1
  92. data/lib/jazzy/themes/apple/templates/header.mustache +4 -4
  93. data/lib/jazzy/themes/apple/templates/task.mustache +3 -8
  94. data/lib/jazzy/themes/fullwidth/assets/js/jquery.min.js +2 -2
  95. data/lib/jazzy/themes/fullwidth/templates/doc.mustache +1 -2
  96. data/lib/jazzy/themes/fullwidth/templates/footer.mustache +1 -1
  97. data/lib/jazzy/themes/fullwidth/templates/header.mustache +4 -4
  98. data/lib/jazzy/themes/fullwidth/templates/task.mustache +3 -8
  99. data/lib/jazzy/themes/jony/assets/js/jquery.min.js +2 -2
  100. data/lib/jazzy/themes/jony/templates/doc.mustache +1 -2
  101. data/lib/jazzy/themes/jony/templates/footer.mustache +1 -1
  102. data/lib/jazzy/themes/jony/templates/header.mustache +2 -2
  103. data/lib/jazzy/themes/jony/templates/task.mustache +3 -8
  104. data/spec/integration_spec.rb +18 -13
  105. metadata +8 -6
data/ObjectiveC.md ADDED
@@ -0,0 +1,208 @@
1
+ This document is about Jazzy's Objective-C documentation generation.
2
+
3
+ It's intended for users who are having problems after trying to follow the
4
+ examples in the [README](README.md#objective-c). It gives some solutions to
5
+ common problems and explains how the system works to help users work through
6
+ uncommon problems.
7
+
8
+ * [How it works](#how-objective-c-docs-generation-works)
9
+ * Common problems:
10
+ * [Apple SDK include failure](#problem-apple-sdk-importinclude-failure)
11
+ * [Non-SDK include failure](#problem-non-sdk-include-failure)
12
+ * [Argument list too long](#problem-argument-list-too-long-e2big-and-more)
13
+ * [Enum cases with wrong doc comment](#problem-enum-cases-have-the-wrong-doc-comment)
14
+ * [Swift API versions missing](#problem-swift-api-versions-are-all-missing)
15
+ * [Swift API versions use `Any`](#problem-swift-api-versions-have-any-instead-of-type-name)
16
+ * [Structural `NS_SWIFT_NAME` not working](#problem-structural-ns_swift_name-not-working)
17
+
18
+ # How Objective-C docs generation works
19
+
20
+ Jazzy uses `libclang` to generate docs for Objective-C projects. You can think
21
+ of this as running some parts of the `clang` compiler against a header file.
22
+ Jazzy refers to this header file as the _umbrella header_ but it does not have
23
+ to be the umbrella header from a Clang module: it's just the header file that
24
+ includes everything to be documented.
25
+
26
+ This means there are two problems to solve:
27
+ 1. What `clang` flags are required; and
28
+ 2. How to pass them to the tools.
29
+
30
+ Jazzy has two modes here: a smart mode that covers 90% of projects and a direct mode where the user provides all the flags.
31
+
32
+ > *Important*: Jazzy does _not_ use any Objective-C build settings from your
33
+ Xcode project or `Package.swift`. If your project needs special settings
34
+ such as `#define`s then you need to repeat those in the Jazzy invocation.
35
+
36
+ ## Direct mode
37
+
38
+ Passing a basic set of `clang` flags looks like this:
39
+
40
+ ```shell
41
+ jazzy ...
42
+ --objc
43
+ --build-tool-arguments
44
+ --objc,MyProject/MyProject.h,--,-x,objective-c,
45
+ -isysroot,$(xcrun --show-sdk-path),
46
+ -I,$(pwd),
47
+ -fmodules
48
+ ```
49
+ The `--build-tool-arguments` are arguments to `sourcekitten`. Everything after
50
+ the `--` are the `clang` flags that will be used with the header file given
51
+ before the `--`.
52
+
53
+ You can try these flags outside of Jazzy's environment:
54
+ ```shell
55
+ clang -c -x objective-c -isysroot $(xcrun --show-sdk-path) -I $(pwd) MyProject/MyProject.h -fmodules
56
+ ```
57
+ (The `-c` stops `clang` from trying to link an executable.)
58
+
59
+ This is a good method of experimenting with compiler flags to get a working
60
+ build without getting bogged down in the Jazzy and SourceKitten layers.
61
+
62
+ ## Smart mode
63
+
64
+ The smart mode takes the variable parts of the basic set of flags and maps
65
+ them from Jazzy flags:
66
+ ```shell
67
+ jazzy ...
68
+ --objc
69
+ --umbrella-header MyProject/MyProject.h
70
+ --framework-root $(pwd)
71
+ [--sdk <sdk name>]
72
+ ```
73
+
74
+ The `--umbrella-header` maps directly to the file passed to `sourcekitten`.
75
+
76
+ The `--framework-root` is used for the `-I` include path, as well as every
77
+ directory beneath it, recursively. So if your project structure looks like:
78
+ ```
79
+ MyProject/
80
+ Sources/
81
+ Main/
82
+ Extension/
83
+ ```
84
+ ... and you pass `--framework-root MyProject`, then the `-I` flags passed to
85
+ `clang` are `-I MyProject -I MyProject/Sources -I MyProject/Sources/Main -I
86
+ MyProject/Sources/Extension`. This feature helps some projects resolve
87
+ `#include` directives.
88
+
89
+ Finally the `--sdk` option is passed through instead of the default `macosx` to
90
+ find the SDK.
91
+
92
+ ## Mixing modes
93
+
94
+ Do not mix modes. For example do not set both `--umbrella-header` and
95
+ `--build-tool-arguments`. Jazzy does not flag this as an error for
96
+ historical compatibility reasons, but the results are at best confusing.
97
+
98
+ # Problem: Apple SDK import/include failure
99
+
100
+ For example `fatal error: module 'UIKit' not found`.
101
+
102
+ This means Jazzy is using the wrong SDK: the default is for macOS which does
103
+ not have `UIKit`. Use `--sdk iphonesimulator`.
104
+
105
+ # Problem: Non-SDK include failure
106
+
107
+ For example `fatal error: 'MyModule/SomeHeader.h' file not found`.
108
+
109
+ This means `clang` is not being passed the right flags to resolve a `#include` /
110
+ `#import`.
111
+
112
+ Start by finding the header file in the filesystem. You might be able to fix
113
+ the problem just by adding extra `-I <path>` flags.
114
+
115
+ Usually though the problem is that Xcode has done something clever that needs
116
+ to be worked around or replicated.
117
+
118
+ Xcode uses technology including Clang header maps to let files be found using
119
+ lines like `#import <ModuleName/Header.h>` even when there is no such
120
+ filesystem directory.
121
+
122
+ To make the Jazzy build work you need to make these `#include`s work. The
123
+ solution depends on your project structure. Some suggestions in rough order
124
+ of complexity:
125
+ * Use symlinks to create an equivalent directory tree. For example if
126
+ `Header.h` is inside `Sources/include` then symlink that directory to
127
+ `ModuleName` and pass `-I $(pwd)`.
128
+
129
+ * Copy/link your header files into a throwaway directory tree that matches
130
+ the required structure and is used just for building docs.
131
+
132
+ * Create a 'docs header file' separate to the framework's regular umbrella
133
+ header that contains only filesystem-correct `#import`s.
134
+
135
+ * If you are happy to build the framework project before generating docs and
136
+ all the problematic paths have the form `ModuleName/PublicHeader.h` then
137
+ have `clang` resolve those includes to the built framework by passing
138
+ `-F <path of directory containing ModuleName.framework>`.
139
+
140
+ * If you are happy to build the project before generating docs then you may
141
+ be able to use the header maps Xcode has generated. Check the build log in
142
+ Xcode to find them and the invocation syntax.
143
+
144
+ * Manually construct an equivalent header map. This is complex not least
145
+ because Apple does not make tools or proper documentation available.
146
+ [An open-source starting point](https://milen.me/writings/swift-module-maps-vfs-overlays-header-maps/).
147
+
148
+ # Problem: Argument list too long `E2BIG` (and more...)
149
+
150
+ For example ``...open4.rb:49:in `exec': Argument list too long - [...]/bin/sourcekitten (Errno::E2BIG)``
151
+
152
+ Can also manifest as 'generally weird' errors such as `sourcekitten` just
153
+ crashing and `fatal error: could not build module 'Foundation'`.
154
+
155
+ This means `--framework-root` is trying to add too many include directories:
156
+ there are too many subdirectories of its parameter. If you cannot change this
157
+ to something more specific that works then you need to use Jazzy's
158
+ [direct mode](#direct-mode) to pass in the correct directories.
159
+
160
+ # Problem: Enum cases have the wrong doc comment
161
+
162
+ If you write an enum case with a doc comment followed by an enum case without
163
+ a doc comment, then both get the same doc comment.
164
+
165
+ This seems to be a bug in `libclang`. The only workaround is to add the missing
166
+ doc comment.
167
+
168
+ # Problem: Swift API versions are all missing
169
+
170
+ This usually means the `clang` flags are malformed in a way that is ignored by
171
+ `libclang` but not by the Swift Objective-C importer.
172
+
173
+ One easy way to accidentally do this is passing `-I` without a path, for
174
+ example `--build-tool-flags ...,-I,-I,Headers`,....
175
+
176
+ This also sometimes happens if you are frequently switching back and forth
177
+ between some Swift / Xcode versions -- it's a bug somewhere in the Apple tools.
178
+ The bad state goes away with time / reboot.
179
+
180
+ # Problem: Swift API versions have `Any` instead of type name
181
+
182
+ Jazzy finds the Swift version of an Objective-C API using the SourceKit
183
+ `source.request.editor.open.interface.header` request on the header file that
184
+ contains the declaration, passing in the same `clang` flags used for the
185
+ umbrella header. [See the code](https://github.com/jpsim/SourceKitten/blob/bed112c313ca8c3c149f8cb84069f1c080e86a7e/Source/SourceKittenFramework/Clang%2BSourceKitten.swift#L202).
186
+
187
+ This means that each header file needs to compile standalone, without
188
+ any implicit dependencies. For example:
189
+ ```
190
+ MyModule.h // umbrella, includes MyClass.h then Utils.h
191
+ MyClass.h // @interface MyClass ... @end
192
+ Utils.h // void my_function( MyClass * myClass);
193
+ ```
194
+ Here, `Utils.h` has an implicit dependency on `MyClass.h` that is normally
195
+ satisfied by the include order of `MyModule.h`. One fix that allows `Utils.h`
196
+ to compile standalone is to add `@class MyClass;`.
197
+
198
+ # Problem: Structural `NS_SWIFT_NAME` not working
199
+
200
+ The `NS_SWIFT_NAME` macro is mostly used to give an Objective-C API a
201
+ different name in Swift. There are no known problems with this part.
202
+
203
+ The macro can also be used to change the 'structure' of an API, for example
204
+ make a C global function appear as a member function in Swift, or make a C
205
+ class appear as a nested type in Swift.
206
+
207
+ Jazzy doesn't understand or communicate these structural changes: you'll need
208
+ to explain it in doc comments.
data/README.md CHANGED
@@ -67,7 +67,7 @@ Here are some resources with tutorials and examples, starting with the most mode
67
67
  * Erica Sadun's [Swift header documentation in Xcode 7](https://ericasadun.com/2015/06/14/swift-header-documentation-in-xcode-7/) post and her [book on Swift Documentation Markup](https://itunes.apple.com/us/book/swift-documentation-markup/id1049010423).
68
68
 
69
69
  For Objective-C documentation the same keywords are supported, but note that the format
70
- is slightly different. In Swift you would write `- returns:`, but in Objective-C you write `@return`. See Apple's [*HeaderDoc User Guide*](https://developer.apple.com/legacy/library/documentation/DeveloperTools/Conceptual/HeaderDoc/tags/tags.html) for more details. **Note: `jazzy` currently does not support _all_ Objective-C keywords listed in this document, only @param, @return, @warning, @see, and @note.**
70
+ is slightly different. In Swift you would write `- returns:`, but in Objective-C you write `@return`. See Apple's [*HeaderDoc User Guide*](https://developer.apple.com/legacy/library/documentation/DeveloperTools/Conceptual/HeaderDoc/tags/tags.html) for more details. **Note: `jazzy` currently does not support _all_ Objective-C keywords listed in this document, only @param, @return, @warning, @see, @note, @code, @endcode, and @c.**
71
71
 
72
72
  Jazzy can also generate cross-references within your documentation. A symbol name in
73
73
  backticks generates a link, for example:
@@ -139,20 +139,36 @@ jazzy \
139
139
 
140
140
  ### Objective-C
141
141
 
142
- To generate documentation for Objective-C headers, you must pass the following
143
- parameters to jazzy:
144
-
142
+ To generate documentation for a simple Objective-C project, you must pass the
143
+ following parameters:
145
144
  * `--objc`
146
145
  * `--umbrella-header ...`
147
146
  * `--framework-root ...`
148
- * `--sdk [iphone|watch|appletv][os|simulator]|macosx` (optional, default value
147
+
148
+ ...and optionally:
149
+ * `--sdk [iphone|watch|appletv][os|simulator]|macosx` (default value
149
150
  of `macosx`)
150
- * `--hide-declarations [objc|swift]` (optional, hides the selected language
151
- declarations)
151
+ * `--hide-declarations [objc|swift]` (hides the selected language declarations)
152
152
 
153
- ##### Example
153
+ For example, this is how the `AFNetworking` docs are generated:
154
+
155
+ ```shell
156
+ jazzy \
157
+ --objc \
158
+ --author AFNetworking \
159
+ --author_url http://afnetworking.com \
160
+ --source-host github \
161
+ --source-host-url https://github.com/AFNetworking/AFNetworking \
162
+ --source-host-files-url https://github.com/AFNetworking/AFNetworking/tree/2.6.2 \
163
+ --module-version 2.6.2 \
164
+ --umbrella-header AFNetworking/AFNetworking.h \
165
+ --framework-root . \
166
+ --module AFNetworking
167
+ ```
154
168
 
155
- This is how Realm Objective-C docs are generated:
169
+ For a more complicated Objective-C project, instead use `--build-tool-arguments`
170
+ to pass arbitrary compiler flags. For example, this is how Realm Objective-C
171
+ docs are generated:
156
172
 
157
173
  ```shell
158
174
  jazzy \
@@ -171,21 +187,8 @@ jazzy \
171
187
  --head "$(cat docs/custom_head.html)"
172
188
  ```
173
189
 
174
- This is how the AFNetworking docs are generated:
175
-
176
- ```shell
177
- jazzy \
178
- --objc \
179
- --author AFNetworking \
180
- --author_url http://afnetworking.com \
181
- --source-host github \
182
- --source-host-url https://github.com/AFNetworking/AFNetworking \
183
- --source-host-files-url https://github.com/AFNetworking/AFNetworking/tree/2.6.2 \
184
- --module-version 2.6.2 \
185
- --umbrella-header AFNetworking/AFNetworking.h \
186
- --framework-root . \
187
- --module AFNetworking
188
- ```
190
+ See [the Objective-C docs](ObjectiveC.md) for more information and some tips
191
+ on troubleshooting.
189
192
 
190
193
  ### Mixed Objective-C / Swift
191
194
 
@@ -260,6 +263,14 @@ Some examples:
260
263
  This implies that `/Build/Products/MyMod.framework` exists and contains
261
264
  a `.swiftmodule`. Again the `--source-directory` is searched by default
262
265
  if `-F` is not passed in.
266
+ 5. With pre-generated symbolgraph files:
267
+ ```shell
268
+ jazzy --module MyMod --swift-build-tool symbolgraph
269
+ --symbolgraph-directory Build/symbolgraphs
270
+ ```
271
+ If you've separately generated symbolgraph files by the use of
272
+ `-emit-symbol-graph`, you can pass the location of these files using
273
+ `--symbolgraph-directory` from where they can be parsed directly.
263
274
 
264
275
  See `swift symbolgraph-extract -help` for all the things you can pass via
265
276
  `--build-tool-arguments`: if your module has dependencies then you may need
@@ -318,6 +329,9 @@ In Swift mode, Jazzy by default documents only `public` and `open` declarations.
318
329
  include declarations with a lower access level, set the `--min-acl` flag to `internal`,
319
330
  `fileprivate`, or `private`.
320
331
 
332
+ By default, Jazzy does not document declarations marked `@_spi` when `--min-acl` is
333
+ set to `public` or `open`. Set the `--include-spi-declarations` flag to include them.
334
+
321
335
  In Objective-C mode, Jazzy documents all declarations found in the `--umbrella-header`
322
336
  header file and any other header files included by it.
323
337
 
@@ -405,6 +419,10 @@ Check the `--min-acl` setting -- see [above](#controlling-what-is-documented).
405
419
  environment variable to point to the Xcode you want before running Jazzy
406
420
  without the `--swift-version` flag.
407
421
 
422
+ ### Objective-C
423
+
424
+ See [this document](ObjectiveC.md).
425
+
408
426
  ### Installation Problems
409
427
 
410
428
  **Can't find header files / clang**
data/Rakefile CHANGED
@@ -105,10 +105,12 @@ begin
105
105
  desc 'Vendors SourceKitten'
106
106
  task :sourcekitten do
107
107
  sk_dir = 'SourceKitten'
108
- Dir.chdir(sk_dir) do
109
- `swift build -c release`
108
+ bin_path = Dir.chdir(sk_dir) do
109
+ build_cmd = 'swift build -c release --arch arm64 --arch x86_64'
110
+ `#{build_cmd}`
111
+ `#{build_cmd} --show-bin-path`.chomp
110
112
  end
111
- FileUtils.cp_r "#{sk_dir}/.build/release/sourcekitten", 'bin'
113
+ FileUtils.cp_r "#{bin_path}/sourcekitten", 'bin'
112
114
  end
113
115
 
114
116
  #-- Theme Dependencies -----------------------------------------------------#
data/bin/sourcekitten CHANGED
Binary file
data/jazzy.gemspec CHANGED
@@ -10,7 +10,7 @@ Gem::Specification.new do |spec|
10
10
  spec.email = ['jp@jpsim.com']
11
11
  spec.summary = 'Soulful docs for Swift & Objective-C.'
12
12
  spec.description = 'Soulful docs for Swift & Objective-C. ' \
13
- "Run in your Xcode project's root directory for " \
13
+ "Run in your SPM or Xcode project's root directory for " \
14
14
  'instant HTML docs.'
15
15
  spec.homepage = 'https://github.com/realm/jazzy'
16
16
  spec.license = 'MIT'
@@ -32,4 +32,5 @@ Gem::Specification.new do |spec|
32
32
  spec.add_development_dependency 'rake', '~> 13.0'
33
33
 
34
34
  spec.required_ruby_version = '>= 2.6.3'
35
+ spec.metadata['rubygems_mfa_required'] = 'true'
35
36
  end
data/js/package-lock.json CHANGED
@@ -1,13 +1,26 @@
1
1
  {
2
+ "name": "jazzy-js",
3
+ "version": "1.0.0",
2
4
  "lockfileVersion": 2,
3
5
  "requires": true,
4
6
  "packages": {
7
+ "": {
8
+ "name": "jazzy-js",
9
+ "version": "1.0.0",
10
+ "license": "MIT",
11
+ "dependencies": {
12
+ "corejs-typeahead": "^1.3.1",
13
+ "jquery": "^3.6.0",
14
+ "katex": "^0.13.3",
15
+ "lunr": "^2.3.9"
16
+ }
17
+ },
5
18
  "node_modules/commander": {
6
- "version": "6.2.1",
7
- "resolved": "https://registry.npmjs.org/commander/-/commander-6.2.1.tgz",
8
- "integrity": "sha512-U7VdrJFnJgo4xjrHpTzu0yrHPGImdsmD95ZlgYSEajAn2JKzDhDTPG9kBTefmObL2w/ngeZnilk+OV9CG3d7UA==",
19
+ "version": "8.3.0",
20
+ "resolved": "https://registry.npmjs.org/commander/-/commander-8.3.0.tgz",
21
+ "integrity": "sha512-OkTL9umf+He2DZkUq8f8J9of7yL6RJKI24dVITBmNfZBmri9zYZQrKkuXiKhyfPSu8tUhnVBB1iKXevvnlR4Ww==",
9
22
  "engines": {
10
- "node": ">= 6"
23
+ "node": ">= 12"
11
24
  }
12
25
  },
13
26
  "node_modules/corejs-typeahead": {
@@ -19,16 +32,20 @@
19
32
  }
20
33
  },
21
34
  "node_modules/jquery": {
22
- "version": "3.6.0",
23
- "resolved": "https://registry.npmjs.org/jquery/-/jquery-3.6.0.tgz",
24
- "integrity": "sha512-JVzAR/AjBvVt2BmYhxRCSYysDsPcssdmTFnzyLEts9qNwmjmu4JTAMYubEfwVOSwpQ1I1sKKFcxhZCI2buerfw=="
35
+ "version": "3.6.1",
36
+ "resolved": "https://registry.npmjs.org/jquery/-/jquery-3.6.1.tgz",
37
+ "integrity": "sha512-opJeO4nCucVnsjiXOE+/PcCgYw9Gwpvs/a6B1LL/lQhwWwpbVEVYDZ1FokFr8PRc7ghYlrFPuyHuiiDNTQxmcw=="
25
38
  },
26
39
  "node_modules/katex": {
27
- "version": "0.13.5",
28
- "resolved": "https://registry.npmjs.org/katex/-/katex-0.13.5.tgz",
29
- "integrity": "sha512-n2uEzFpNFUOAlWs0eCgmT82LQyP+BlS45yBgnLRqe+ENp3+FEM3lM+cJwZwwxxONFgayyq1fm6n+w35vo2MaUg==",
40
+ "version": "0.13.24",
41
+ "resolved": "https://registry.npmjs.org/katex/-/katex-0.13.24.tgz",
42
+ "integrity": "sha512-jZxYuKCma3VS5UuxOx/rFV1QyGSl3Uy/i0kTJF3HgQ5xMinCQVF8Zd4bMY/9aI9b9A2pjIBOsjSSm68ykTAr8w==",
43
+ "funding": [
44
+ "https://opencollective.com/katex",
45
+ "https://github.com/sponsors/katex"
46
+ ],
30
47
  "dependencies": {
31
- "commander": "^6.0.0"
48
+ "commander": "^8.0.0"
32
49
  },
33
50
  "bin": {
34
51
  "katex": "cli.js"
@@ -40,5 +57,37 @@
40
57
  "integrity": "sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow=="
41
58
  }
42
59
  },
43
- "dependencies": {}
60
+ "dependencies": {
61
+ "commander": {
62
+ "version": "8.3.0",
63
+ "resolved": "https://registry.npmjs.org/commander/-/commander-8.3.0.tgz",
64
+ "integrity": "sha512-OkTL9umf+He2DZkUq8f8J9of7yL6RJKI24dVITBmNfZBmri9zYZQrKkuXiKhyfPSu8tUhnVBB1iKXevvnlR4Ww=="
65
+ },
66
+ "corejs-typeahead": {
67
+ "version": "1.3.1",
68
+ "resolved": "https://registry.npmjs.org/corejs-typeahead/-/corejs-typeahead-1.3.1.tgz",
69
+ "integrity": "sha512-fyNlBNWJNL6EQUnJyAunEzBzRcwR2cEHtZXBi2pndHPOJ/wpOf3wbS+/Oh+kYYS5sKowQcs0LFwMSl6Y2Xeqkw==",
70
+ "requires": {
71
+ "jquery": ">=1.11"
72
+ }
73
+ },
74
+ "jquery": {
75
+ "version": "3.6.1",
76
+ "resolved": "https://registry.npmjs.org/jquery/-/jquery-3.6.1.tgz",
77
+ "integrity": "sha512-opJeO4nCucVnsjiXOE+/PcCgYw9Gwpvs/a6B1LL/lQhwWwpbVEVYDZ1FokFr8PRc7ghYlrFPuyHuiiDNTQxmcw=="
78
+ },
79
+ "katex": {
80
+ "version": "0.13.24",
81
+ "resolved": "https://registry.npmjs.org/katex/-/katex-0.13.24.tgz",
82
+ "integrity": "sha512-jZxYuKCma3VS5UuxOx/rFV1QyGSl3Uy/i0kTJF3HgQ5xMinCQVF8Zd4bMY/9aI9b9A2pjIBOsjSSm68ykTAr8w==",
83
+ "requires": {
84
+ "commander": "^8.0.0"
85
+ }
86
+ },
87
+ "lunr": {
88
+ "version": "2.3.9",
89
+ "resolved": "https://registry.npmjs.org/lunr/-/lunr-2.3.9.tgz",
90
+ "integrity": "sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow=="
91
+ }
92
+ }
44
93
  }