jazzy 0.13.5 → 0.13.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b896e2cc19ed17de08bbaf77655ce4cc28ba3b086c4b324c6f3c15d3f61c5c2
-  data.tar.gz: 6dda6fa99cc9c4282f3818f405f218b23d22e57b6869be208082e36b25873dd0
+  metadata.gz: 20ab471420ed44e905319be51f0410c0571efa3f56902834b6e7d47f4f66fd0a
+  data.tar.gz: 2bfa14b53c563edb51d4cf0f0a4041859929561b725324761f17568410819838
 SHA512:
-  metadata.gz: 7d3a45bc3b94976166452b9ddf2c411dff01acedd555ba7b124f5eb66c078f5cdab652958a83017e1a253384b874316bf25e523a6eb6f814eb8c04b282063ee5
-  data.tar.gz: e7816087c597af5c4811f7c1155160242268b6beb25c610d93f571e749bc2c92edc7633712eed492d882d23f9576af98637ef46e8857ed4f547608ede6387439
+  metadata.gz: 6c5b2eeb4b88f7cf4c8b406bc627c754b50f7f95cd9c555127998530e201b7dfc0e86c237cff3f3dff71c85fa6c979733e0b75de6fd4c52333de8e9d9cf741b0
+  data.tar.gz: 672470f7c618f5fc659035a2705674b3804558abc86d58c788943f1495e7e4e3de9447ae6ee46156b68c11776d32986551c91a7f7b222fda455e59f89bc91973

data/.circleci/config.yml

@@ -17,11 +17,12 @@ jobs:
 
   swift:
     macos:
-      xcode: "11.4.0"
+      xcode: "12.1.0"
     environment: *bundler-environment
     steps:
       - checkout
       - restore_cache: *restore-mac-bundler-cache
+      - run: echo 'chruby 2.6' >> ~/.bash_profile
       - run: bundle install
       - run: git submodule update --init --recursive
       - run: bundle exec rake swift_spec
@@ -29,11 +30,12 @@ jobs:
 
   objc:
     macos:
-      xcode: "11.4.0"
+      xcode: "12.1.0"
     environment: *bundler-environment
     steps:
       - checkout
       - restore_cache: *restore-mac-bundler-cache
+      - run: echo 'chruby 2.6' >> ~/.bash_profile
       - run: bundle install
       - run: git submodule update --init --recursive
       - run: bundle exec rake objc_spec
@@ -41,13 +43,14 @@ jobs:
 
   cocoapods:
     macos:
-      xcode: "11.4.0"
+      xcode: "12.1.0"
     environment: *bundler-environment
     steps:
       - checkout
       - restore_cache:
           key: cocoapods
       - restore_cache: *restore-mac-bundler-cache
+      - run: echo 'chruby 2.6' >> ~/.bash_profile
       - run: bundle install
       - run: git submodule update --init --recursive
       - run: bundle exec rake cocoapods_spec

data/CHANGELOG.md

@@ -1,3 +1,21 @@
+## 0.13.6
+
+##### Breaking
+
+* None.
+
+##### Enhancements
+
+* Support documentation generation from `.swiftmodule` binaries using
+  `--swift-build-tool symbolgraph` with Swift 5.3.  
+  [John Fairhurst](https://github.com/johnfairh)
+
+##### Bug Fixes
+
+* Always bypass codesigning when building Xcode projects.  
+  [John Fairhurst](https://github.com/johnfairh)
+  [#1183](https://github.com/realm/jazzy/issues/1183)
+
 ## 0.13.5
 
 ##### Breaking

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    jazzy (0.13.5)
+    jazzy (0.13.6)
       cocoapods (~> 1.5)
       mustache (~> 1.1)
       open4
@@ -15,14 +15,14 @@ GEM
   remote: https://rubygems.org/
   specs:
     CFPropertyList (3.0.2)
-    activesupport (4.2.11.3)
-      i18n (~> 0.7)
+    activesupport (5.2.4.4)
+      concurrent-ruby (~> 1.0, >= 1.0.2)
+      i18n (>= 0.7, < 2)
       minitest (~> 5.1)
-      thread_safe (~> 0.3, >= 0.3.4)
       tzinfo (~> 1.1)
     addressable (2.7.0)
       public_suffix (>= 2.0.2, < 5.0)
-    algoliasearch (1.27.3)
+    algoliasearch (1.27.5)
       httpclient (~> 2.8, >= 2.8.3)
       json (>= 1.5.1)
     ast (2.4.1)
@@ -36,15 +36,14 @@ GEM
     clintegracon (0.7.0)
       colored (~> 1.2)
       diffy
-    cocoapods (1.9.3)
-      activesupport (>= 4.0.2, < 5)
+    cocoapods (1.10.0)
+      addressable (~> 2.6)
       claide (>= 1.0.2, < 2.0)
-      cocoapods-core (= 1.9.3)
+      cocoapods-core (= 1.10.0)
       cocoapods-deintegrate (>= 1.0.3, < 2.0)
-      cocoapods-downloader (>= 1.2.2, < 2.0)
+      cocoapods-downloader (>= 1.4.0, < 2.0)
       cocoapods-plugins (>= 1.0.0, < 2.0)
       cocoapods-search (>= 1.0.0, < 2.0)
-      cocoapods-stats (>= 1.0.0, < 2.0)
       cocoapods-trunk (>= 1.4.0, < 2.0)
       cocoapods-try (>= 1.1.0, < 2.0)
       colored2 (~> 3.1)
@@ -54,33 +53,33 @@ GEM
       molinillo (~> 0.6.6)
       nap (~> 1.0)
       ruby-macho (~> 1.4)
-      xcodeproj (>= 1.14.0, < 2.0)
-    cocoapods-core (1.9.3)
-      activesupport (>= 4.0.2, < 6)
+      xcodeproj (>= 1.19.0, < 2.0)
+    cocoapods-core (1.10.0)
+      activesupport (> 5.0, < 6)
+      addressable (~> 2.6)
       algoliasearch (~> 1.0)
       concurrent-ruby (~> 1.1)
       fuzzy_match (~> 2.0.4)
       nap (~> 1.0)
       netrc (~> 0.11)
+      public_suffix
       typhoeus (~> 1.0)
     cocoapods-deintegrate (1.0.4)
-    cocoapods-downloader (1.3.0)
+    cocoapods-downloader (1.4.0)
     cocoapods-plugins (1.0.0)
       nap
     cocoapods-search (1.0.0)
-    cocoapods-stats (1.1.0)
     cocoapods-trunk (1.5.0)
       nap (>= 0.8, < 2.0)
       netrc (~> 0.11)
     cocoapods-try (1.2.0)
     colored (1.2)
     colored2 (3.1.2)
-    concurrent-ruby (1.1.6)
+    concurrent-ruby (1.1.7)
     cork (0.3.0)
       colored2 (~> 3.1)
-    crack (0.4.3)
-      safe_yaml (~> 1.0.0)
-    danger (8.0.2)
+    crack (0.4.4)
+    danger (8.2.0)
       claide (~> 1.0)
       claide-plugins (>= 0.9.2)
       colored2 (~> 3.1)
@@ -88,17 +87,18 @@ GEM
       faraday (>= 0.9.0, < 2.0)
       faraday-http-cache (~> 2.0)
       git (~> 1.7)
-      kramdown (~> 2.0)
+      kramdown (~> 2.3)
       kramdown-parser-gfm (~> 1.0)
       no_proxy_fix
       octokit (~> 4.7)
       terminal-table (~> 1)
-    diffy (3.3.0)
+    diffy (3.4.0)
     escape (0.0.4)
     ethon (0.12.0)
       ffi (>= 1.3.0)
-    faraday (1.0.1)
+    faraday (1.1.0)
       multipart-post (>= 1.2, < 3)
+      ruby2_keywords
     faraday-http-cache (2.2.0)
       faraday (>= 0.8)
     ffi (1.13.1)
@@ -109,7 +109,7 @@ GEM
       rchardet (~> 1.8)
     hashdiff (1.0.1)
     httpclient (2.8.3)
-    i18n (0.9.5)
+    i18n (1.8.5)
       concurrent-ruby (~> 1.0)
     json (2.3.1)
     kramdown (2.3.0)
@@ -117,35 +117,35 @@ GEM
     kramdown-parser-gfm (1.1.0)
       kramdown (~> 2.0)
     liferaft (0.0.6)
-    minitest (5.14.1)
+    minitest (5.14.2)
     mocha (1.11.2)
     mocha-on-bacon (0.2.3)
       mocha (>= 0.13.0)
     molinillo (0.6.6)
     multipart-post (2.1.1)
     mustache (1.1.1)
-    nanaimo (0.2.6)
+    nanaimo (0.3.0)
     nap (1.1.0)
     netrc (0.11.0)
     no_proxy_fix (0.1.2)
-    octokit (4.18.0)
+    octokit (4.19.0)
       faraday (>= 0.9)
       sawyer (~> 0.8.0, >= 0.5.3)
     open4 (1.3.4)
-    parallel (1.19.2)
-    parser (2.7.1.4)
+    parallel (1.20.0)
+    parser (2.7.2.0)
       ast (~> 2.4.1)
     powerpack (0.1.2)
     prettybacon (0.0.2)
       bacon (~> 1.2)
-    public_suffix (4.0.5)
+    public_suffix (4.0.6)
     rainbow (2.2.2)
       rake
     rake (13.0.1)
     rchardet (1.8.0)
     redcarpet (3.5.0)
     rexml (3.2.4)
-    rouge (3.20.0)
+    rouge (3.24.0)
     rubocop (0.49.0)
       parallel (~> 1.10)
       parser (>= 2.3.3.1, < 3.0)
@@ -155,7 +155,7 @@ GEM
       unicode-display_width (~> 1.0, >= 1.0.1)
     ruby-macho (1.4.0)
     ruby-progressbar (1.10.1)
-    safe_yaml (1.0.5)
+    ruby2_keywords (0.0.2)
     sassc (2.4.0)
       ffi (~> 1.9)
     sawyer (0.8.2)
@@ -167,21 +167,21 @@ GEM
     thread_safe (0.3.6)
     typhoeus (1.4.0)
       ethon (>= 0.9.0)
-    tzinfo (1.2.7)
+    tzinfo (1.2.8)
       thread_safe (~> 0.1)
     unicode-display_width (1.7.0)
-    webmock (3.8.3)
+    webmock (3.9.4)
       addressable (>= 2.3.6)
       crack (>= 0.3.2)
       hashdiff (>= 0.4.0, < 2.0.0)
     xcinvoke (0.3.0)
       liferaft (~> 0.0.6)
-    xcodeproj (1.17.0)
+    xcodeproj (1.19.0)
       CFPropertyList (>= 2.3.3, < 4.0)
       atomos (~> 0.1.3)
       claide (>= 1.0.2, < 2.0)
       colored2 (~> 3.1)
-      nanaimo (~> 0.2.6)
+      nanaimo (~> 0.3.0)
 
 PLATFORMS
   ruby

data/README.md

@@ -8,13 +8,14 @@
 
 Both Swift and Objective-C projects are supported.
 
-*SwiftPM support was recently added, so please report any issues you find.*
-
 Instead of parsing your source files, `jazzy` hooks into [Clang][clang] and
 [SourceKit][sourcekit] to use the [AST][ast] representation of your code and
 its comments for more accurate results. The output matches the look and feel
 of Apple’s official reference documentation, post WWDC 2014.
 
+Jazzy can also generate documentation from compiled swift modules [using their
+symbol graph](#docs-from-swiftmodules-or-frameworks) instead of source code.
+
 ![Screenshot](images/screenshot.jpg)
 
 This project adheres to the [Contributor Covenant Code of Conduct](https://realm.io/conduct).
@@ -49,13 +50,14 @@ succeed too!
 
 If Jazzy generates docs for the wrong module then use `--module` to tell it which
 one you'd prefer.  If this doesn't help, and you're using Xcode, then try passing
-extra arguments to `xcodebuild`, for example `jazzy --build-tool-arguments -target,MyTarget`.
+extra arguments to `xcodebuild`, for example
+`jazzy --build-tool-arguments -scheme,MyScheme,-target,MyTarget`.
 
 You can set options for your project’s documentation in a configuration file,
 `.jazzy.yaml` by default. For a detailed explanation and an exhaustive list of
 all available options, run `jazzy --help config`.
 
-### Supported keywords
+### Supported documentation keywords
 
 Swift documentation is written in markdown and supports a number of special keywords.
 For a complete list and examples, see Erica Sadun's post on [*Swift header documentation in Xcode 7*](https://ericasadun.com/2015/06/14/swift-header-documentation-in-xcode-7/),
@@ -200,6 +202,57 @@ sourcekitten doc --objc $(pwd)/MyProject/MyProject.h \
 jazzy --sourcekitten-sourcefile swiftDoc.json,objcDoc.json
 ```
 
+### Docs from `.swiftmodule`s or frameworks
+
+*This feature is new and relies on a new Swift feature: there may be crashes
+and mistakes: reports welcome.*
+
+Swift 5.3 adds support for symbol graph generation from `.swiftmodule` files.
+This looks to be part of Apple's toolchain for generating their online docs.
+
+Jazzy can use this to generate API documentation.  This is faster than using
+the source code directly but does have limitations: for example documentation
+comments are available only for `public` declarations, and the presentation of
+Swift extensions may not match the way they are written in code.
+
+Some examples:
+
+1. Generate docs for the Apple Combine framework for macOS:
+   ```shell
+   jazzy --module Combine --swift-build-tool symbolgraph
+   ```
+   The SDK's library directories are included in the search path by
+   default.
+2. Same but for iOS:
+   ```shell
+   jazzy --module Combine --swift-build-tool symbolgraph
+         --sdk iphoneos
+         --build-tool-arguments --target,arm64-apple-ios14.1
+   ```
+   The `target` is the LLVM target triple and needs to match the SDK.  The
+   default here is the target of the host system that Jazzy is running on,
+   something like `x86_64-apple-darwin19.6.0`.
+3. Generate docs for a personal `.swiftmodule`:
+   ```shell
+   jazzy --module MyMod --swift-build-tool symbolgraph
+         --build-tool-arguments -I,/Build/Products
+   ```
+   This implies that `/Build/Products/MyMod.swiftmodule` exists.  Jazzy's
+   `--source-directory` (default current directory) is searched by default,
+   so you only need the `-I` override if that's not enough.
+4. For a personal framework:
+   ```shell
+   jazzy --module MyMod --swift-build-tool symbolgraph
+         --build-tool-arguments -F,/Build/Products
+   ```
+   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.
+
+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
+to add various search path options to let Swift load it.
+
 ### Themes
 
 Three themes are provided with jazzy: `apple` (default), `fullwidth` and `jony`.

data/lib/jazzy/config.rb

@@ -219,14 +219,14 @@ module Jazzy
         end
       end
 
-    SWIFT_BUILD_TOOLS = %w[spm xcodebuild].freeze
+    SWIFT_BUILD_TOOLS = %w[spm xcodebuild symbolgraph].freeze
 
     config_attr :swift_build_tool,
       command_line: "--swift-build-tool #{SWIFT_BUILD_TOOLS.join(' | ')}",
-      description: 'Control whether Jazzy uses Swift Package Manager or '\
-                   'xcodebuild to build the module to be documented.  By '\
-                   'default it uses xcodebuild if there is a .xcodeproj '\
-                   'file in the source directory.',
+      description: 'Control whether Jazzy uses Swift Package Manager, '\
+                   'xcodebuild, or swift-symbolgraph to build the module '\
+                   'to be documented.  By default it uses xcodebuild if '\
+                   'there is a .xcodeproj file in the source directory.',
       parse: ->(tool) do
         return tool.to_sym if SWIFT_BUILD_TOOLS.include?(tool)
         raise "Unsupported swift_build_tool #{tool}, "\

data/lib/jazzy/doc_builder.rb

@@ -14,6 +14,7 @@ require 'jazzy/source_declaration'
 require 'jazzy/source_document'
 require 'jazzy/source_module'
 require 'jazzy/sourcekitten'
+require 'jazzy/symbol_graph'
 
 module Jazzy
   # This module handles HTML generation, file writing, asset copying,
@@ -72,6 +73,8 @@ module Jazzy
       elsif options.podspec_configured
         pod_documenter = PodspecDocumenter.new(options.podspec)
         stdout = pod_documenter.sourcekitten_output(options)
+      elsif options.swift_build_tool == :symbolgraph
+        stdout = SymbolGraph.build(options)
       else
         stdout = Dir.chdir(options.source_directory) do
           arguments = SourceKitten.arguments_from_options(options)
@@ -192,7 +195,10 @@ module Jazzy
 
         lint_report = {
           warnings: warnings.sort_by do |w|
-            [w[:file], w[:line] || 0, w[:symbol], w[:symbol_kind]]
+            [w[:file] || Pathname(''),
+             w[:line] || 0,
+             w[:symbol],
+             w[:symbol_kind]]
           end,
           source_directory: options.source_directory,
         }

data/lib/jazzy/gem_version.rb

@@ -1,3 +1,3 @@
 module Jazzy
-  VERSION = '0.13.5'.freeze unless defined? Jazzy::VERSION
+  VERSION = '0.13.6'.freeze unless defined? Jazzy::VERSION
 end

data/lib/jazzy/sourcekitten.rb

@@ -325,17 +325,16 @@ module Jazzy
         end
     end
 
-    def self.should_mark_undocumented(filepath)
-      source_directory = Config.instance.source_directory.to_s
-      (filepath || '').start_with?(source_directory)
+    # Call things undocumented if they were compiled properly
+    # and came from our module.
+    def self.should_mark_undocumented(declaration)
+      declaration.usr && !declaration.modulename
     end
 
     def self.process_undocumented_token(doc, declaration)
       make_default_doc_info(declaration)
 
-      filepath = doc['key.filepath']
-
-      if !declaration.swift? || should_mark_undocumented(filepath)
+      if !declaration.swift? || should_mark_undocumented(declaration)
         @stats.add_undocumented(declaration)
         return nil if @skip_undocumented
         declaration.abstract = undocumented_abstract

data/lib/jazzy/symbol_graph.rb

@@ -0,0 +1,95 @@
+require 'set'
+require 'jazzy/symbol_graph/graph'
+require 'jazzy/symbol_graph/constraint'
+require 'jazzy/symbol_graph/symbol'
+require 'jazzy/symbol_graph/relationship'
+require 'jazzy/symbol_graph/sym_node'
+require 'jazzy/symbol_graph/ext_node'
+
+# This is the top-level symbolgraph driver that deals with
+# figuring out arguments, running the tool, and loading the
+# results.
+
+module Jazzy
+  module SymbolGraph
+    # Run `swift symbolgraph-extract` with configured args,
+    # 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 @).
+          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
+    end
+
+    # Figure out the args to pass to symbolgraph-extract
+    # rubocop:disable Metrics/CyclomaticComplexity
+    def self.arguments(config, output_path)
+      if config.module_name.empty?
+        raise 'error: `--swift-build-tool symbolgraph` requires `--module`.'
+      end
+
+      user_args = config.build_tool_arguments.join
+
+      if user_args =~ /--(?:module-name|minimum-access-level|output-dir)/
+        raise 'error: `--build-tool-arguments` for '\
+          "`--swift-build-tool symbolgraph` can't use `--module`, "\
+          '`--minimum-access-level`, or `--output-dir`.'
+      end
+
+      # Default set
+      args = [
+        "--module-name=#{config.module_name}",
+        '--minimum-access-level=private',
+        "--output-dir=#{output_path}",
+        '--skip-synthesized-members',
+      ]
+
+      # Things user can override
+      args.append("--sdk=#{sdk(config)}") unless user_args =~ /--sdk/
+      args.append("--target=#{target}") unless user_args =~ /--target/
+      args.append("-F=#{config.source_directory}") unless user_args =~ /-F(?!s)/
+      args.append("-I=#{config.source_directory}") unless user_args =~ /-I/
+
+      args + config.build_tool_arguments
+    end
+    # rubocop:enable Metrics/CyclomaticComplexity
+
+    # Get the SDK path.  On !darwin this just isn't needed.
+    def self.sdk(config)
+      `xcrun --show-sdk-path --sdk #{config.sdk}`.chomp
+    end
+
+    # Guess a default LLVM target.  Feels like the tool should figure this
+    # out from sdk + the binary somehow?
+    def self.target
+      `swift -version` =~ /Target: (.*?)$/
+      Regexp.last_match[1] || 'x86_64-apple-macosx10.15'
+    end
+
+    # This is a last-ditch fallback for when symbolgraph doesn't
+    # provide a name - at least conforming external types to local
+    # protocols.
+    def self.demangle(usr)
+      args = %w[demangle -simplified -compact].append(usr.sub(/^s:/, 's'))
+      output, = Executable.execute_command('swift', args, true)
+      return output.chomp
+    rescue
+      usr
+    end
+  end
+end