jazzy 0.14.0 → 0.14.3
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 +5 -5
- data/.rubocop.yml +62 -2
- data/CHANGELOG.md +75 -0
- data/CONTRIBUTING.md +1 -1
- data/Gemfile.lock +76 -66
- data/ObjectiveC.md +208 -0
- data/README.md +42 -24
- data/Rakefile +5 -3
- data/bin/sourcekitten +0 -0
- data/jazzy.gemspec +2 -1
- data/js/package-lock.json +61 -12
- data/lib/jazzy/config.rb +54 -35
- data/lib/jazzy/doc_builder.rb +9 -2
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_AMS-Regular.ttf +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_AMS-Regular.woff +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_AMS-Regular.woff2 +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Caligraphic-Bold.ttf +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Caligraphic-Bold.woff +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Caligraphic-Bold.woff2 +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Caligraphic-Regular.ttf +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Caligraphic-Regular.woff +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Caligraphic-Regular.woff2 +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Fraktur-Bold.ttf +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Fraktur-Bold.woff +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Fraktur-Bold.woff2 +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Fraktur-Regular.ttf +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Fraktur-Regular.woff +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Fraktur-Regular.woff2 +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-Bold.ttf +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-Bold.woff +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-Bold.woff2 +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-BoldItalic.ttf +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-BoldItalic.woff +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-BoldItalic.woff2 +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-Italic.ttf +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-Italic.woff +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-Italic.woff2 +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-Regular.ttf +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-Regular.woff +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Main-Regular.woff2 +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Math-BoldItalic.ttf +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Math-BoldItalic.woff +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Math-BoldItalic.woff2 +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Math-Italic.ttf +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Math-Italic.woff +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Math-Italic.woff2 +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_SansSerif-Bold.ttf +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_SansSerif-Bold.woff +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_SansSerif-Bold.woff2 +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_SansSerif-Italic.ttf +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_SansSerif-Italic.woff +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_SansSerif-Italic.woff2 +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_SansSerif-Regular.ttf +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_SansSerif-Regular.woff +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_SansSerif-Regular.woff2 +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Script-Regular.ttf +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Script-Regular.woff +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Script-Regular.woff2 +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size1-Regular.ttf +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size1-Regular.woff +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size1-Regular.woff2 +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size2-Regular.ttf +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size2-Regular.woff +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size2-Regular.woff2 +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size3-Regular.ttf +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size3-Regular.woff +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size3-Regular.woff2 +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size4-Regular.ttf +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size4-Regular.woff +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Size4-Regular.woff2 +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Typewriter-Regular.ttf +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Typewriter-Regular.woff +0 -0
- data/lib/jazzy/extensions/katex/css/fonts/KaTeX_Typewriter-Regular.woff2 +0 -0
- 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/jazzy_markdown.rb +13 -3
- data/lib/jazzy/search_builder.rb +3 -5
- data/lib/jazzy/source_declaration/type.rb +26 -2
- data/lib/jazzy/source_declaration.rb +13 -2
- data/lib/jazzy/sourcekitten.rb +58 -10
- data/lib/jazzy/stats.rb +11 -2
- data/lib/jazzy/symbol_graph/graph.rb +7 -2
- data/lib/jazzy/symbol_graph/relationship.rb +6 -0
- data/lib/jazzy/symbol_graph/sym_node.rb +14 -1
- data/lib/jazzy/symbol_graph/symbol.rb +36 -10
- data/lib/jazzy/symbol_graph.rb +30 -19
- data/lib/jazzy/themes/apple/assets/js/jquery.min.js +2 -2
- data/lib/jazzy/themes/apple/templates/doc.mustache +1 -2
- data/lib/jazzy/themes/apple/templates/footer.mustache +1 -1
- data/lib/jazzy/themes/apple/templates/header.mustache +4 -4
- data/lib/jazzy/themes/apple/templates/task.mustache +3 -8
- data/lib/jazzy/themes/fullwidth/assets/js/jquery.min.js +2 -2
- data/lib/jazzy/themes/fullwidth/templates/doc.mustache +1 -2
- data/lib/jazzy/themes/fullwidth/templates/footer.mustache +1 -1
- data/lib/jazzy/themes/fullwidth/templates/header.mustache +4 -4
- data/lib/jazzy/themes/fullwidth/templates/task.mustache +3 -8
- data/lib/jazzy/themes/jony/assets/js/jquery.min.js +2 -2
- data/lib/jazzy/themes/jony/templates/doc.mustache +1 -2
- data/lib/jazzy/themes/jony/templates/footer.mustache +1 -1
- data/lib/jazzy/themes/jony/templates/header.mustache +2 -2
- data/lib/jazzy/themes/jony/templates/task.mustache +3 -8
- data/spec/integration_spec.rb +18 -13
- 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 @
|
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
|
143
|
-
parameters
|
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
|
-
|
147
|
+
|
148
|
+
...and optionally:
|
149
|
+
* `--sdk [iphone|watch|appletv][os|simulator]|macosx` (default value
|
149
150
|
of `macosx`)
|
150
|
-
* `--hide-declarations [objc|swift]` (
|
151
|
-
declarations)
|
151
|
+
* `--hide-declarations [objc|swift]` (hides the selected language declarations)
|
152
152
|
|
153
|
-
|
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
|
-
|
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
|
-
|
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
|
-
|
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 "#{
|
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": "
|
7
|
-
"resolved": "https://registry.npmjs.org/commander/-/commander-
|
8
|
-
"integrity": "sha512-
|
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": ">=
|
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.
|
23
|
-
"resolved": "https://registry.npmjs.org/jquery/-/jquery-3.6.
|
24
|
-
"integrity": "sha512-
|
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.
|
28
|
-
"resolved": "https://registry.npmjs.org/katex/-/katex-0.13.
|
29
|
-
"integrity": "sha512-
|
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": "^
|
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
|
}
|