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 <johnfairh@gmail.com>

.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

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
 

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

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. '\

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