From 819ae6fae4b3f4e3d77a91194a2da3cba5d6074c Mon Sep 17 00:00:00 2001 From: Nathan Wong Date: Tue, 30 Nov 2021 09:36:36 +0000 Subject: [PATCH] Support pre-generated Swift symbolgraph files (#1294) Since Swift 5.5, the Swift compiler has supported the `-emit-symbol-graph` and `-emit-symbol-graph-dir` flags to directly create symbolgraph 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. Co-authored-by: John Fairhurst --- .github/workflows/Tests.yml | 6 ++--- CHANGELOG.md | 3 ++- README.md | 8 +++++++ lib/jazzy/config.rb | 6 +++++ lib/jazzy/symbol_graph.rb | 45 +++++++++++++++++++++++-------------- 5 files changed, 47 insertions(+), 21 deletions(-) diff --git a/.github/workflows/Tests.yml b/.github/workflows/Tests.yml index 18cc9428e..d1754fe07 100644 --- a/.github/workflows/Tests.yml +++ b/.github/workflows/Tests.yml @@ -15,14 +15,14 @@ jobs: with: ruby-version: 2.6 bundler-cache: true + - name: Rubocop + run: | + bundle exec rake rubocop - name: Danger env: DANGER_GITHUB_API_TOKEN: ${{ secrets.GITHUB_TOKEN }} run: | bundle exec danger --verbose - - name: Rubocop - run: | - bundle exec rake rubocop spec: runs-on: macos-11 diff --git a/CHANGELOG.md b/CHANGELOG.md index 428c491dd..24c115254 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,7 +9,8 @@ ##### Enhancements -* None. +* Support using pre-generated symbolgraph files in Swift symbolgraph mode. + [Nathan Wong](https://github.com/esteluk) ##### Bug Fixes diff --git a/README.md b/README.md index a076c3eaa..cc0589825 100644 --- a/README.md +++ b/README.md @@ -260,6 +260,14 @@ Some examples: This implies that `/Build/Products/MyMod.framework` exists and contains a `.swiftmodule`. Again the `--source-directory` is searched by default if `-F` is not passed in. +5. With pre-generated symbolgraph files: + ```shell + jazzy --module MyMod --swift-build-tool symbolgraph + --symbolgraph-directory Build/symbolgraphs + ``` + 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. See `swift symbolgraph-extract -help` for all the things you can pass via `--build-tool-arguments`: if your module has dependencies then you may need diff --git a/lib/jazzy/config.rb b/lib/jazzy/config.rb index d40ca07cb..759c2e776 100644 --- a/lib/jazzy/config.rb +++ b/lib/jazzy/config.rb @@ -193,6 +193,12 @@ def hide_objc? default: Pathname.pwd, parse: ->(sd) { expand_path(sd) } + config_attr :symbolgraph_directory, + command_line: '--symbolgraph-directory DIRPATH', + description: 'A directory containing a set of Swift Symbolgraph files ' \ + 'representing the module to be documented', + parse: ->(sd) { expand_path(sd) } + config_attr :excluded_files, command_line: ['-e', '--exclude filepath1,filepath2,…filepathN', Array], description: 'Source file pathnames to be excluded from documentation. '\ diff --git a/lib/jazzy/symbol_graph.rb b/lib/jazzy/symbol_graph.rb index 81d2850c7..8a7b59a2f 100644 --- a/lib/jazzy/symbol_graph.rb +++ b/lib/jazzy/symbol_graph.rb @@ -14,27 +14,24 @@ module Jazzy module SymbolGraph - # Run `swift symbolgraph-extract` with configured args, - # parse the results, and return as JSON in SourceKit[ten] + # Find swift symbol graph files, either having been passed + # in directly, or generated by running`swift symbolgraph-extract` + # with configured args. + # Then parse the results, and return as JSON in SourceKit[ten] # format. def self.build(config) - Dir.mktmpdir do |tmp_dir| - args = arguments(config, tmp_dir) + if config.symbolgraph_directory.nil? + Dir.mktmpdir do |tmp_dir| + args = arguments(config, tmp_dir) - Executable.execute_command('swift', - args.unshift('symbolgraph-extract'), - true) # raise on error + Executable.execute_command('swift', + args.unshift('symbolgraph-extract'), + true) # raise on error - Dir[tmp_dir + '/*.symbols.json'].map do |filename| - # The @ part is for extensions in our module (before the @) - # of types in another module (after the @). - File.basename(filename) =~ /(.*?)(@(.*?))?\.symbols/ - module_name = Regexp.last_match[3] || Regexp.last_match[1] - { - filename => - Graph.new(File.read(filename), module_name).to_sourcekit, - } - end.to_json + parse_symbols(tmp_dir) + end + else + parse_symbols(config.symbolgraph_directory.to_s) end end @@ -69,6 +66,20 @@ def self.arguments(config, output_path) args + config.build_tool_arguments end + # Parse the symbol files in the given directory + def self.parse_symbols(directory) + Dir[directory + '/*.symbols.json'].map do |filename| + # The @ part is for extensions in our module (before the @) + # of types in another module (after the @). + File.basename(filename) =~ /(.*?)(@(.*?))?\.symbols/ + module_name = Regexp.last_match[3] || Regexp.last_match[1] + { + filename => + Graph.new(File.read(filename), module_name).to_sourcekit, + } + end.to_json + end + # Get the SDK path. On !darwin this just isn't needed. def self.sdk(config) `xcrun --show-sdk-path --sdk #{config.sdk}`.chomp