jazzy 0.2.2 → 0.2.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 19c85014e711d310498a311bb30099ee0a6c9bbb
-  data.tar.gz: d6c589b0ef0551de858cfc471da17108fe762972
+  metadata.gz: ec769c8636609b8b4d6557633fe765929a0c6734
+  data.tar.gz: b10db798f53a77bceed7800b3c474528371c381f
 SHA512:
-  metadata.gz: 78fdb1e5bb33da47b03ec512f448873fa1bfc46a08cd96cb633080c4b6ed81593f14c6269710c3da2291825c0a938e0aeca47be2b88de7d6175d68689f196647
-  data.tar.gz: 3d27a0e9fbcab0e860873c9e00594c6e43d533ad710cc0fc562c146adfd180e5841d18c2c17370fbdfe758901ab8951279c1d87ae397d146ff23dc03d7ebecbc
+  metadata.gz: 3efe0871f0c10b0e06dcd62fcc535e72a4adfbd938bfd8268e720ada1b625dba34e7bb91d9f2ebe240465b93d2e7ffdc95061e883b67b8e7c52def23ab014352
+  data.tar.gz: 998599ca369d570fb1e92132c6f96d10e5a031b48119a84d5c38cf393e8512e9b1c40b38d005a71dd8051652b549b73e713fae84e5f65b65e932f98ea80bbdec

data/.travis.yml

@@ -1,5 +1,5 @@
 language: objective-c
-osx_image: beta-xcode6.3
+osx_image: xcode6.4
 cache: bundler
 branches:
   only:

data/CHANGELOG.md

@@ -1,3 +1,22 @@
+## 0.2.3
+
+##### Breaking
+
+* None.
+
+##### Enhancements
+
+* The `jazzy` CLI now accepts a `--swift-version` option (defaulting to 1.2),
+  and will automatically find an appropriate Xcode installation.  
+  [Samuel Giddins](https://github.com/segiddins)
+  [#214](https://github.com/realm/jazzy/issues/214)
+
+##### Bug Fixes
+
+* Declarations with no USR will no longer be documented.  
+  [JP Simard](https://github.com/jpsim)
+
+
 ## 0.2.2
 
 ##### Breaking

data/Gemfile.lock

@@ -1,14 +1,15 @@
 PATH
   remote: .
   specs:
-    jazzy (0.2.2)
-      cocoapods (~> 0.37)
+    jazzy (0.2.3)
+      cocoapods (~> 0.38)
       mustache (~> 0.99)
       open4
       redcarpet (~> 3.2)
       rouge (~> 1.5)
       sass (~> 3.4)
       sqlite3 (~> 1.3)
+      xcinvoke (~> 0.2.0)
 
 GEM
   remote: http://rubygems.org/
@@ -24,30 +25,33 @@ GEM
     astrolabe (1.3.0)
       parser (>= 2.2.0.pre.3, < 3.0)
     bacon (1.2.0)
-    claide (0.8.2)
+    claide (0.9.1)
     clintegracon (0.5.3)
       colored (~> 1.2)
       diffy
-    cocoapods (0.37.2)
+    cocoapods (0.38.2)
       activesupport (>= 3.2.15)
-      claide (~> 0.8.1)
-      cocoapods-core (= 0.37.2)
-      cocoapods-downloader (~> 0.9.0)
+      claide (~> 0.9.1)
+      cocoapods-core (= 0.38.2)
+      cocoapods-downloader (~> 0.9.1)
       cocoapods-plugins (~> 0.4.2)
+      cocoapods-stats (~> 0.5.3)
       cocoapods-trunk (~> 0.6.1)
       cocoapods-try (~> 0.4.5)
       colored (~> 1.2)
       escape (~> 0.0.4)
-      molinillo (~> 0.2.3)
+      molinillo (~> 0.3.1)
       nap (~> 0.8)
-      xcodeproj (~> 0.24.2)
-    cocoapods-core (0.37.2)
+      xcodeproj (~> 0.26.3)
+    cocoapods-core (0.38.2)
       activesupport (>= 3.2.15)
       fuzzy_match (~> 2.0.4)
       nap (~> 0.8.0)
     cocoapods-downloader (0.9.1)
     cocoapods-plugins (0.4.2)
       nap
+    cocoapods-stats (0.5.3)
+      nap (~> 0.8)
     cocoapods-trunk (0.6.1)
       nap (>= 0.8)
       netrc (= 0.7.8)
@@ -60,13 +64,14 @@ GEM
     fuzzy_match (2.0.4)
     i18n (0.7.0)
     json (1.8.3)
+    liferaft (0.0.4)
     metaclass (0.0.4)
     minitest (5.7.0)
     mocha (1.1.0)
       metaclass (~> 0.0.1)
     mocha-on-bacon (0.2.2)
       mocha (>= 0.13.0)
-    molinillo (0.2.3)
+    molinillo (0.3.1)
     mustache (0.99.8)
     nap (0.8.0)
     netrc (0.7.8)
@@ -89,7 +94,7 @@ GEM
       ruby-progressbar (~> 1.4)
     ruby-progressbar (1.6.0)
     safe_yaml (1.0.4)
-    sass (3.4.15)
+    sass (3.4.16)
     slop (3.6.0)
     sqlite3 (1.3.10)
     thread_safe (0.3.5)
@@ -98,8 +103,11 @@ GEM
     webmock (1.20.0)
       addressable (>= 2.3.6)
       crack (>= 0.3.2)
-    xcodeproj (0.24.3)
+    xcinvoke (0.2.0)
+      liferaft (~> 0.0.4)
+    xcodeproj (0.26.3)
       activesupport (>= 3)
+      claide (~> 0.9.1)
       colored (~> 1.2)
 
 PLATFORMS
@@ -119,4 +127,4 @@ DEPENDENCIES
   webmock
 
 BUNDLED WITH
-   1.10.5
+   1.10.6

data/Rakefile

@@ -28,7 +28,7 @@ begin
   desc 'Run specs'
   task :spec do
     title 'Running Unit Tests'
-    files = FileList['spec/**/*_spec.rb']
+    files = FileList['spec/*_spec.rb']
       .exclude('spec/integration_spec.rb').shuffle.join(' ')
     sh "bundle exec bacon #{files}"
     sh 'bundle exec bacon spec/integration_spec.rb'
@@ -72,7 +72,7 @@ begin
 
   require 'rubocop/rake_task'
   RuboCop::RakeTask.new(:rubocop) do |task|
-    task.patterns = %w(lib spec Rakefile Gemfile jazzy.gemspec)
+    task.patterns = %w(lib spec/*.rb Rakefile Gemfile jazzy.gemspec)
   end
 
   #-- SourceKitten -----------------------------------------------------------#

data/jazzy.gemspec

@@ -19,13 +19,14 @@ Gem::Specification.new do |spec|
 
   spec.extensions    = ['lib/jazzy/SourceKitten/Rakefile']
 
-  spec.add_runtime_dependency 'cocoapods', '~> 0.37'
+  spec.add_runtime_dependency 'cocoapods', '~> 0.38'
   spec.add_runtime_dependency 'mustache', '~> 0.99'
   spec.add_runtime_dependency 'open4'
   spec.add_runtime_dependency 'redcarpet', '~> 3.2'
   spec.add_runtime_dependency 'rouge', '~> 1.5'
   spec.add_runtime_dependency 'sass', '~> 3.4'
   spec.add_runtime_dependency 'sqlite3', '~> 1.3'
+  spec.add_runtime_dependency 'xcinvoke', '~> 0.2.0'
 
   spec.add_development_dependency 'bundler', '~> 1.7'
   spec.add_development_dependency 'rake', '~> 10.3'

data/lib/jazzy/config.rb

@@ -31,6 +31,7 @@ module Jazzy
     attr_accessor :source_directory
     attr_accessor :excluded_files
     attr_accessor :template_directory
+    attr_accessor :swift_version
 
     def initialize
       PodspecDocumenter.configure(self, Dir['*.podspec{,.json}'].first)
@@ -47,6 +48,7 @@ module Jazzy
       self.source_directory = Pathname.pwd
       self.excluded_files = []
       self.template_directory = Pathname(__FILE__).parent + 'templates'
+      self.swift_version = '1.2'
     end
 
     def podspec=(podspec)
@@ -174,6 +176,10 @@ module Jazzy
           config.template_directory = Pathname(template_directory)
         end
 
+        opt.on('--swift-version VERSION') do |swift_version|
+          config.swift_version = swift_version
+        end
+
         opt.on('--readme FILEPATH',
                'The path to a markdown README file') do |readme|
           config.readme_path = Pathname(readme)

data/lib/jazzy/doc_builder.rb

@@ -193,24 +193,25 @@ module Jazzy
     end
 
     def self.should_link_to_github(file)
-      developer_directory = SourceKitten.xcode_developer_directory
-      return unless developer_directory && file
-      !file.start_with?(developer_directory.realpath.to_s)
+      return unless file
+      file = file.realpath.to_path
+      source_directory = Config.instance.source_directory.to_path
+      file.start_with?(source_directory)
     end
 
     # Construct Github token URL
     # @param [Hash] item Parsed doc child item
     # @param [Config] options Build options
     def self.gh_token_url(item, source_module)
-      if source_module.github_file_prefix && should_link_to_github(item.file)
-        relative_file_path = item.file.gsub(`pwd`.strip, '')
-        if item.start_line && (item.start_line != item.end_line)
-          gh_line = "#L#{item.start_line}-L#{item.end_line}"
-        else
-          gh_line = "#L#{item.line}"
-        end
-        source_module.github_file_prefix + relative_file_path + gh_line
+      return unless github_prefix = source_module.github_file_prefix
+      return unless should_link_to_github(item.file)
+      if item.start_line && (item.start_line != item.end_line)
+        gh_line = "#L#{item.start_line}-L#{item.end_line}"
+      else
+        gh_line = "#L#{item.line}"
       end
+      relative_file_path = item.file.realpath.relative_path_from(Pathname.pwd)
+      "#{github_prefix}/#{relative_file_path}#{gh_line}"
     end
 
     # Build mustache item for a top-level doc

data/lib/jazzy/executable.rb

@@ -17,7 +17,7 @@ module Jazzy
     end
 
     class << self
-      def execute_command(executable, args, raise_on_failure)
+      def execute_command(executable, args, raise_on_failure, env: {})
         require 'shellwords'
         bin = `which #{executable.to_s.shellescape}`.strip
         raise "Unable to locate the executable `#{executable}`" if bin.empty?
@@ -27,7 +27,7 @@ module Jazzy
         stdout, stderr = IO.new, IO.new($stderr)
 
         options = { stdout: stdout, stderr: stderr, status: true }
-        status  = Open4.spawn(bin, *args, options)
+        status  = Open4.spawn(env, bin, *args, options)
         unless status.success?
           full_command = "#{bin.shellescape} #{args.map(&:shellescape)}"
           output = stdout.to_s << stderr.to_s

data/lib/jazzy/gem_version.rb

@@ -1,3 +1,3 @@
 module Jazzy
-  VERSION = '0.2.2' unless defined? Jazzy::VERSION
+  VERSION = '0.2.3' unless defined? Jazzy::VERSION
 end

data/lib/jazzy/podspec_documenter.rb

@@ -75,6 +75,7 @@ module Jazzy
         c.installation_root = Pathname(Dir.mktmpdir)
         c.installation_root.rmtree if c.installation_root.exist?
         c.integrate_targets = false
+        c.deduplicate_targets = false
       end
     end
 

data/lib/jazzy/sourcekitten.rb

@@ -1,5 +1,6 @@
 require 'json'
 require 'pathname'
+require 'xcinvoke'
 
 require 'jazzy/config'
 require 'jazzy/executable'
@@ -12,7 +13,6 @@ module Jazzy
   module SourceKitten
     @documented_count = 0
     @undocumented_tokens = []
-    @expected_swift_version = '1.2'
 
     # Group root-level docs by type and add as children to a group doc element
     def self.group_docs(docs, type)
@@ -39,49 +39,17 @@ module Jazzy
         else
           # Don't create HTML page for this doc if it doesn't have children
           # Instead, make its link a hash-link on its parent's page
-          id = doc.usr
-          unless id
-            id = doc.name || 'unknown'
-            warn "`#{id}` has no USR. First make sure all modules used in " \
-              'your project have been imported. If all used modules are ' \
-              'imported, please report this problem by filing an issue at ' \
-              'https://github.com/realm/jazzy/issues along with your Xcode ' \
-              'project. If this token is declared in an `#if` block, please ' \
-              'ignore this message.'
-          end
-          doc.url = parents.join('/') + '.html#/' + id
+          doc.url = parents.join('/') + '.html#/' + doc.usr
         end
       end
     end
 
-    def self.assert_xcode_location
-      expected_xcode_select_path =
-        Pathname('/Applications/Xcode.app/Contents/Developer')
-      return if xcode_developer_directory == expected_xcode_select_path
-      raise 'Please install or symlink Xcode 6.3 in ' \
-            "#{expected_xcode_select_path} and set as active developer " \
-            'directory by running `sudo xcode-select -s ' \
-            "#{expected_xcode_select_path}`"
-    end
-
-    def self.xcode_developer_directory
-      dir = Pathname(`xcode-select -p`.chomp)
-      dir.directory? ? dir.expand_path : nil
-    end
-
-    def self.assert_swift_version
-      swift_version = `xcrun swift --version` =~ /Swift version ([\d\.]+)/ &&
-        Regexp.last_match[1]
-      return if swift_version == @expected_swift_version
-      raise "Jazzy only works with Swift #{@expected_swift_version}."
-    end
-
     # Run sourcekitten with given arguments and return STDOUT
     def self.run_sourcekitten(arguments)
-      assert_xcode_location
-      assert_swift_version
+      xcode = XCInvoke::Xcode.find_swift_version(Config.instance.swift_version)
       bin_path = Pathname(__FILE__).parent + 'SourceKitten/sourcekitten'
-      output, _ = Executable.execute_command(bin_path, arguments, true)
+      output, _ = Executable.execute_command(bin_path, arguments, true,
+                                             env: xcode.as_env)
       output
     end
 
@@ -100,6 +68,15 @@ module Jazzy
     end
 
     def self.should_document?(doc)
+      unless doc['key.usr']
+        warn "`#{doc['key.name']}` has no USR. First make sure all modules "  \
+              'used in your project have been imported. If all used modules ' \
+              'are imported, please report this problem by filing an issue '  \
+              'at https://github.com/realm/jazzy/issues along with your '     \
+              'Xcode project. If this token is declared in an `#if` block, '  \
+              'please ignore this message.'
+        return false
+      end
       return false if doc['key.doc.comment'].to_s.include?(':nodoc:')
 
       # Always document extensions, since we can't tell what ACL they are
@@ -186,6 +163,7 @@ module Jazzy
 
     # rubocop:disable Metrics/MethodLength
     # rubocop:disable Metrics/CyclomaticComplexity
+    # rubocop:disable Metrics/PerceivedComplexity
     def self.make_source_declarations(docs)
       declarations = []
       current_mark = SourceMark.new
@@ -207,7 +185,7 @@ module Jazzy
                 "for `#{declaration.type.kind}`."
         end
 
-        declaration.file = doc['key.filepath']
+        declaration.file = Pathname(doc['key.filepath']) if doc['key.filepath']
         declaration.usr  = doc['key.usr']
         declaration.name = doc['key.name']
         declaration.mark = current_mark
@@ -222,6 +200,7 @@ module Jazzy
       end
       declarations
     end
+    # rubocop:enable Metrics/PerceivedComplexity
     # rubocop:enable Metrics/CyclomaticComplexity
     # rubocop:enable Metrics/MethodLength
 

data/spec/integration_spec.rb

@@ -102,6 +102,23 @@ describe_cli 'jazzy' do
                             '--skip-undocumented'
     end
 
+    describe 'Creates Realm Swift docs' do
+      realm_version = '0.93.2'
+      behaves_like cli_spec 'document_realm_swift',
+                            '--author Realm ' \
+                            '--author_url "https://realm.io" ' \
+                            '--github_url ' \
+                            'https://github.com/realm/realm-cocoa ' \
+                            '--github-file-prefix https://github.com/realm/' \
+                            "realm-cocoa/tree/v#{realm_version} " \
+                            '--module RealmSwift ' \
+                            "--module-version #{realm_version} " \
+                            '--root-url https://realm.io/docs/swift/' \
+                            "#{realm_version}/api/ " \
+                            '--xcodebuild-arguments ' \
+                            '"-project,RealmSwift.xcodeproj,-dry-run" '
+    end
+
     describe 'Creates docs for a podspec with dependencies and subspecs' do
       behaves_like cli_spec 'document_moya_podspec',
                             '--podspec=Moya.podspec'

data/spec/sourcekitten_spec.rb

@@ -2,30 +2,5 @@ require File.expand_path('../spec_helper', __FILE__)
 
 module Jazzy
   describe SourceKitten do
-    it 'validates the xcode-select path' do
-      SourceKitten.stubs(:`)
-        .returns '/Applications/Xcode.app/Contents/Developer'
-      should.not.raise { SourceKitten.assert_xcode_location }
-
-      SourceKitten.stubs(:`)
-        .returns '/Applications/Xcode-Beta.app/Contents/Developer'
-      should.raise { SourceKitten.assert_xcode_location }.message.should
-        .match %r{Please install or symlink Xcode.*/Applications/Xcode.app}
-    end
-
-    it 'validates the current xcode version' do
-      SourceKitten.stubs(:`).returns <<-O
-Apple Swift version 1.2 (swiftlang-602.0.49.6 clang-602.0.49)
-Target: x86_64-apple-darwin14.3.0
-      O
-      should.not.raise { SourceKitten.assert_swift_version }
-
-      SourceKitten.stubs(:`).returns <<-O
-Swift version 1.1 (swift-600.0.57.4)
-Target: x86_64-apple-darwin14.1.0
-      O
-      should.raise { SourceKitten.assert_swift_version }.message.should
-        .match /Jazzy.*Swift 1\.2/
-    end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jazzy
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.2.3
 platform: ruby
 authors:
 - JP Simard
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-07-07 00:00:00.000000000 Z
+date: 2015-07-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cocoapods
@@ -18,14 +18,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.37'
+        version: '0.38'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.37'
+        version: '0.38'
 - !ruby/object:Gem::Dependency
   name: mustache
   requirement: !ruby/object:Gem::Requirement
@@ -110,6 +110,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.3'
+- !ruby/object:Gem::Dependency
+  name: xcinvoke
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -243,7 +257,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.4.8
 signing_key: 
 specification_version: 4
 summary: Soulful docs for Swift & Objective-C.