From 4d609a91c53cb3125f5ca19936ea280ddd9d40d3 Mon Sep 17 00:00:00 2001 From: Nathan Wong Date: Mon, 29 Nov 2021 15:21:32 +0000 Subject: [PATCH 1/4] Support pre-generated Swift symbolgraph files 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. --- CHANGELOG.md | 3 ++- README.md | 8 +++++++ lib/jazzy/config.rb | 6 +++++ lib/jazzy/symbol_graph.rb | 50 ++++++++++++++++++++++++--------------- spec/integration_spec.rb | 19 +++++++++++++-- 5 files changed, 64 insertions(+), 22 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 428c491dd..d13bed789 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..438c13ae9 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..1537b561b 100644 --- a/lib/jazzy/symbol_graph.rb +++ b/lib/jazzy/symbol_graph.rb @@ -14,27 +14,25 @@ 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) - - 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 + + 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 + + parseSymbols(tmp_dir) + end + else + parseSymbols(config.symbolgraph_directory.to_s) end end @@ -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) + 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 diff --git a/spec/integration_spec.rb b/spec/integration_spec.rb index 0d3a95e74..708311663 100644 --- a/spec/integration_spec.rb +++ b/spec/integration_spec.rb @@ -40,17 +40,19 @@ # @return [Pathname] The root of the repo. # -ROOT = Pathname.new(File.expand_path('..', __dir__)) unless defined? ROOT -$:.unshift((ROOT + 'spec').to_s) require 'rubygems' require 'bundler/setup' require 'pretty_bacon' require 'colored' require 'CLIntegracon' +require 'pathname' require 'cocoapods' +ROOT = Pathname.new(File.expand_path('..', __dir__)) unless defined? ROOT +$:.unshift((ROOT + 'spec').to_s) + def configure_cocoapods Pod::Config.instance.with_changes(silent: true) do Pod::Command::Setup.invoke @@ -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 + build_path = Dir.getwd + 'tmp/.build' + package_path = + ROOT + 'spec/integration_specs/misc_jazzy_symgraph_features/before' + "swift build --package-path #{package_path} --build-path #{build_path} " \ + "-Xswiftc -emit-symbol-graph -Xswiftc -emit-symbol-graph-dir -Xswiftc #{build_path}" + module_path = `swift build --build-path #{build_path} --show-bin-path` + + behaves_like cli_spec 'misc_jazzy_symgraph_features', + '--swift-build-tool symbolgraph ' \ + "--symbolgraph_directory #{build_path} " + end end if !spec_subset || spec_subset == 'swift' describe 'jazzy cocoapods' do From 3042e753ad92999281fe24bcfe64768511834dbb Mon Sep 17 00:00:00 2001 From: Nathan Wong Date: Mon, 29 Nov 2021 19:03:25 +0000 Subject: [PATCH 2/4] Address feedback in PR * Conform to contribution guidelines * Use correct command line arguments in README examples * Use snake_case for method name --- CHANGELOG.md | 2 +- README.md | 4 ++-- lib/jazzy/symbol_graph.rb | 6 +++--- spec/integration_spec.rb | 8 ++++---- 4 files changed, 10 insertions(+), 10 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d13bed789..24c115254 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,7 +9,7 @@ ##### Enhancements -* Support using pre-generated symbolgraph files in Swift symbolgraph mode. +* 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 438c13ae9..cc0589825 100644 --- a/README.md +++ b/README.md @@ -263,11 +263,11 @@ Some examples: 5. With pre-generated symbolgraph files: ```shell jazzy --module MyMod --swift-build-tool symbolgraph - --symbolgraph_directory Build/symbolgraphs + --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. + `--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/symbol_graph.rb b/lib/jazzy/symbol_graph.rb index 1537b561b..6a2b7e3da 100644 --- a/lib/jazzy/symbol_graph.rb +++ b/lib/jazzy/symbol_graph.rb @@ -29,10 +29,10 @@ def self.build(config) args.unshift('symbolgraph-extract'), true) # raise on error - parseSymbols(tmp_dir) + parse_symbols(tmp_dir) end else - parseSymbols(config.symbolgraph_directory.to_s) + parse_symbols(config.symbolgraph_directory.to_s) end end @@ -68,7 +68,7 @@ def self.arguments(config, output_path) end # Parse the symbol files in the given directory - def self.parseSymbols(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 @). diff --git a/spec/integration_spec.rb b/spec/integration_spec.rb index 708311663..d9894ee75 100644 --- a/spec/integration_spec.rb +++ b/spec/integration_spec.rb @@ -242,16 +242,16 @@ def configure_cocoapods end describe 'Creates docs for Swift project from symbolgraph files' do - build_path = Dir.getwd + 'tmp/.build' + build_path = Dir.getwd + '/tmp/.build' package_path = ROOT + 'spec/integration_specs/misc_jazzy_symgraph_features/before' - "swift build --package-path #{package_path} --build-path #{build_path} " \ - "-Xswiftc -emit-symbol-graph -Xswiftc -emit-symbol-graph-dir -Xswiftc #{build_path}" + `swift build --package-path #{package_path} --build-path #{build_path} \ + -Xswiftc -emit-symbol-graph -Xswiftc -emit-symbol-graph-dir -Xswiftc #{build_path}` module_path = `swift build --build-path #{build_path} --show-bin-path` behaves_like cli_spec 'misc_jazzy_symgraph_features', '--swift-build-tool symbolgraph ' \ - "--symbolgraph_directory #{build_path} " + "--symbolgraph-directory #{build_path} " end end if !spec_subset || spec_subset == 'swift' From 85ad16dc0f94528c523115b3726779775dcce363 Mon Sep 17 00:00:00 2001 From: Nathan Wong Date: Mon, 29 Nov 2021 19:17:23 +0000 Subject: [PATCH 3/4] Remove new test spec --- spec/integration_spec.rb | 19 ++----------------- 1 file changed, 2 insertions(+), 17 deletions(-) diff --git a/spec/integration_spec.rb b/spec/integration_spec.rb index d9894ee75..0d3a95e74 100644 --- a/spec/integration_spec.rb +++ b/spec/integration_spec.rb @@ -40,19 +40,17 @@ # @return [Pathname] The root of the repo. # +ROOT = Pathname.new(File.expand_path('..', __dir__)) unless defined? ROOT +$:.unshift((ROOT + 'spec').to_s) require 'rubygems' require 'bundler/setup' require 'pretty_bacon' require 'colored' require 'CLIntegracon' -require 'pathname' require 'cocoapods' -ROOT = Pathname.new(File.expand_path('..', __dir__)) unless defined? ROOT -$:.unshift((ROOT + 'spec').to_s) - def configure_cocoapods Pod::Config.instance.with_changes(silent: true) do Pod::Command::Setup.invoke @@ -240,19 +238,6 @@ def configure_cocoapods '--swift-build-tool symbolgraph ' \ "--build-tool-arguments -I,#{module_path} " end - - describe 'Creates docs for Swift project from symbolgraph files' do - build_path = Dir.getwd + '/tmp/.build' - package_path = - ROOT + 'spec/integration_specs/misc_jazzy_symgraph_features/before' - `swift build --package-path #{package_path} --build-path #{build_path} \ - -Xswiftc -emit-symbol-graph -Xswiftc -emit-symbol-graph-dir -Xswiftc #{build_path}` - module_path = `swift build --build-path #{build_path} --show-bin-path` - - behaves_like cli_spec 'misc_jazzy_symgraph_features', - '--swift-build-tool symbolgraph ' \ - "--symbolgraph-directory #{build_path} " - end end if !spec_subset || spec_subset == 'swift' describe 'jazzy cocoapods' do From f67b6c2502058039d255b2961c859e554e98d259 Mon Sep 17 00:00:00 2001 From: John Fairhurst Date: Tue, 30 Nov 2021 09:24:05 +0000 Subject: [PATCH 4/4] CI fixups Fix Rubocop errors Reorder jobs so at least Rubocop runs on forks --- .github/workflows/Tests.yml | 6 +++--- lib/jazzy/symbol_graph.rb | 11 +++++------ 2 files changed, 8 insertions(+), 9 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/lib/jazzy/symbol_graph.rb b/lib/jazzy/symbol_graph.rb index 6a2b7e3da..8a7b59a2f 100644 --- a/lib/jazzy/symbol_graph.rb +++ b/lib/jazzy/symbol_graph.rb @@ -20,16 +20,15 @@ module SymbolGraph # Then parse the results, and return as JSON in SourceKit[ten] # format. def self.build(config) - if config.symbolgraph_directory.nil? Dir.mktmpdir do |tmp_dir| - args = arguments(config, 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 - parse_symbols(tmp_dir) + parse_symbols(tmp_dir) end else parse_symbols(config.symbolgraph_directory.to_s)