Support pre-generated Swift symbolgraph files #1294
Conversation
Since Swift 5.5, the Swift compiler has supported the `-emit-symbol-graph` and `-emit-symbol-graph-dir` flags to directly create Symbol graph files as part of the compilation process. If a developer has access to these files, it's not necessary for Jazzy to use `symbolgraph-extract` to attempt to separately generate them. This commit adds a `--symbolgraph_directory` configuration option to Jazzy. If this option is provided, Jazzy skips the generation of symbolgraph files and directly parses any `*.symbol.json` files in the given directory.
esteluk
changed the title
|
Sorry, meant to raise this initially on my fork rather than here, but having done so it might as well stay open... I found this a valuable change because I was struggling a little bit to find the correct If this is a direction that you'd prefer not to go down, I'd be happy to close the PR. |
CHANGELOG.md
Outdated
| @@ -9,7 +9,8 @@ | |||
|
|
|||
| ##### Enhancements | |||
|
|
|||
| * None. | |||
| * Support using pre-generated symbolgraph files in Swift symbolgraph mode. | |||
There was a problem hiding this comment.
Need end-of-line spaces for markdown, see CONTRIBUTING.md.
README.md
Outdated
| 5. With pre-generated symbolgraph files: | ||
| ```shell | ||
| jazzy --module MyMod --swift-build-tool symbolgraph | ||
| --symbolgraph_directory Build/symbolgraphs |
There was a problem hiding this comment.
Should be --symbolgraph-directory here? With dash not underscore?
There was a problem hiding this comment.
Yeah sorry, I'd been staring at the yaml files too much!
README.md
Outdated
| ``` | ||
| If you've separately generated symbolgraph files by the use of | ||
| `-emit-symbol-graph`, you can pass the location of these files using | ||
| `--symbolgraph_directory` from where they can be parsed directly. |
lib/jazzy/symbol_graph.rb
Outdated
| @@ -69,6 +67,20 @@ def self.arguments(config, output_path) | |||
| args + config.build_tool_arguments | |||
| end | |||
|
|
|||
| # Parse the symbol files in the given directory | |||
| def self.parseSymbols(directory) | |||
There was a problem hiding this comment.
snake-case for Ruby, self.parse_symbols
spec/integration_spec.rb
Outdated
| @@ -238,6 +240,19 @@ def configure_cocoapods | |||
| '--swift-build-tool symbolgraph ' \ | |||
| "--build-tool-arguments -I,#{module_path} " | |||
| end | |||
|
|
|||
| describe 'Creates docs for Swift project from symbolgraph files' do | |||
There was a problem hiding this comment.
I'd prefer to not change this file, it's quite a lot of overhead to get this working and adding a entire new output set adds change-review burden in the future as well. I appreciate the effort to add some kind of test for the feature but jazzy doesn't have a way of doing convenient unit-testing.
There was a problem hiding this comment.
Fair enough, that makes sense. I was hoping that it would be possible to reuse the same before/after states as the main symbolgraph tests, but I think there are some differences in output that would make this impossible. Giving it half-of another shot, but remove this test shortly otherwise.
|
I'm happy to merge this option -- left a few comments. I don't know what's up with Danger in CI, maybe we have something misconfigured for forks, but you should be able to run |
* Conform to contribution guidelines * Use correct command line arguments in README examples * Use snake_case for method name
|
Turns out Danger + GitHub actions is broken on forks due to secret handling. |
|
All done - thanks for the PR! |
Since Swift 5.5, the Swift compiler has supported the
-emit-symbol-graphand
-emit-symbol-graph-dirflags to directly create Symbol graph filesas part of the compilation process. If a developer has access to these
files, it's not necessary for Jazzy to use
symbolgraph-extractto attemptto separately generate them.
This commit adds a
--symbolgraph_directoryconfiguration option to Jazzy.If this option is provided, Jazzy skips the generation of symbolgraph files
and directly parses any
*.symbol.jsonfiles in the given directory.