Support pre-generated Swift symbolgraph files

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,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

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