jazzy 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 7f8bf2a0d123cd83a7fd7c6d8928c07735f1c4da
-  data.tar.gz: c8dcc98da703c0184eab711e25dfe7a22efa2e55
+  metadata.gz: f2baa2074d45fd8acf5c3a9afcaf52f9f4614608
+  data.tar.gz: 57e138cb29858db55c158aa6006114f9f09a2fa2
 SHA512:
-  metadata.gz: 9f5c0e859e43e9416f70a5225affc7ee6967ff59925405826453320da6a7b92b3515c510983b6b50c13e94d995c84198b0bc1c7f5c950e3fbe456a6d734066db
-  data.tar.gz: d5617da8fd853e0c5c8277109f6ca017937e3f792104343790a7eb628a6ff746a184e361bb27ce3d2342af4952b6e377bc97561a72fc388be0c24ff4d96a9744
+  metadata.gz: d14e639dda30299184b75472b051bba215675390e7f99b302de680987bf7dbfc2a8f324148f38ad1b22fd272e17cdc447bcdcc5d39c4ff5d8b804a051103139c
+  data.tar.gz: 7540ba48abfb300b5787b96afc56350c0a79e7434cb194cc47a9aeb2694143b06640db746d2c208c835f528bd833da115fc8ce5b04590ae68ea826785d831166

data/CHANGELOG.md

@@ -1,6 +1,4 @@
-## Master
-
-[sourcekitten](https://github.com/jpsim/sourcekitten/compare/0.3.1...master)
+## 0.1.3
 
 ##### Breaking
 
@@ -8,11 +6,34 @@
 
 ##### Enhancements
 
-* None.
+* Improve the styling of `dl` elements (parsed key-value pairs).  
+  [segiddins](https://github.com/segiddins)
+
+* Raise exceptions if Xcode requirements aren't met.  
+  [JP Simard](https://github.com/jpsim)
 
 ##### Bug Fixes
 
-* None.
+* No longer count initializers with parameters as undocumented.  
+  [JP Simard](https://github.com/jpsim)
+  [#183](https://github.com/realm/jazzy/issues/183)
+
+* No longer crash when a token is missing a USR.  
+  [JP Simard](https://github.com/jpsim)
+  [#171](https://github.com/realm/jazzy/issues/171)
+
+* Fixed encoding issues in some environments.  
+  [James Barrow](https://github.com/Baza207)
+  [#152](https://github.com/realm/jazzy/issues/152)
+
+* No longer count undocumented externally declared tokens as undocumented.  
+  [JP Simard](https://github.com/jpsim)
+  [#188](https://github.com/realm/jazzy/issues/188)
+
+* Fixed `--source-directory` CLI option.  
+  [JP Simard](https://github.com/jpsim)
+  [#177](https://github.com/realm/jazzy/issues/177)
+
 
 ## 0.1.2
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    jazzy (0.1.2)
+    jazzy (0.1.3)
       activesupport (~> 4.1)
       cocoapods (~> 0.36.0.rc.1)
       mustache (~> 0.99)
@@ -14,7 +14,7 @@ PATH
 GEM
   remote: http://rubygems.org/
   specs:
-    activesupport (4.2.0)
+    activesupport (4.2.1)
       i18n (~> 0.7)
       json (~> 1.7, >= 1.7.7)
       minitest (~> 5.1)
@@ -29,28 +29,28 @@ GEM
     clintegracon (0.5.3)
       colored (~> 1.2)
       diffy
-    cocoapods (0.36.0.rc.1)
+    cocoapods (0.36.0)
       activesupport (>= 3.2.15)
       claide (~> 0.8.1)
-      cocoapods-core (= 0.36.0.rc.1)
+      cocoapods-core (= 0.36.0)
       cocoapods-downloader (~> 0.8.1)
       cocoapods-plugins (~> 0.4.1)
-      cocoapods-trunk (~> 0.5.1)
+      cocoapods-trunk (~> 0.6.0)
       cocoapods-try (~> 0.4.3)
       colored (~> 1.2)
       escape (~> 0.0.4)
       molinillo (~> 0.2.1)
       nap (~> 0.8)
       open4 (~> 1.3)
-      xcodeproj (~> 0.22.0)
-    cocoapods-core (0.36.0.rc.1)
+      xcodeproj (~> 0.23.0)
+    cocoapods-core (0.36.0)
       activesupport (>= 3.2.15)
       fuzzy_match (~> 2.0.4)
       nap (~> 0.8.0)
     cocoapods-downloader (0.8.1)
     cocoapods-plugins (0.4.1)
       nap
-    cocoapods-trunk (0.5.1)
+    cocoapods-trunk (0.6.0)
       nap (>= 0.8)
       netrc (= 0.7.8)
     cocoapods-try (0.4.3)
@@ -94,16 +94,16 @@ GEM
       ruby-progressbar (~> 1.4)
     ruby-progressbar (1.6.0)
     safe_yaml (1.0.4)
-    sass (3.4.11)
+    sass (3.4.13)
     slop (3.6.0)
     sqlite3 (1.3.10)
-    thread_safe (0.3.4)
+    thread_safe (0.3.5)
     tzinfo (1.2.2)
       thread_safe (~> 0.1)
     webmock (1.20.0)
       addressable (>= 2.3.6)
       crack (>= 0.3.2)
-    xcodeproj (0.22.0)
+    xcodeproj (0.23.0)
       activesupport (>= 3)
       colored (~> 1.2)
 

data/Rakefile

@@ -28,8 +28,10 @@ begin
   desc 'Run specs'
   task :spec do
     title 'Running Unit Tests'
-    files = FileList['spec/**/*_spec.rb'].shuffle.join(' ')
+    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'
 
     Rake::Task['rubocop'].invoke
   end
@@ -92,7 +94,7 @@ begin
     File.open("#{destination}/Rakefile", 'w') { |f| f.write rakefile }
   end
 
-rescue LoadError, NameError
+rescue LoadError, NameError => e
   $stderr.puts "\033[0;31m" \
     '[!] Some Rake tasks haven been disabled because the environment' \
     ' couldn’t be loaded. Be sure to run `rake bootstrap` first.' \

data/lib/jazzy.rb

@@ -1,2 +1,4 @@
 require 'jazzy/config'
 require 'jazzy/doc_builder'
+
+Encoding.default_external = Encoding::UTF_8

data/lib/jazzy/assets/css/jazzy.css.scss

@@ -1,6 +1,7 @@
 $doc_coverage_color: #999;
 $content_wrapper_width: 980px;
 $code-font: 12px Menlo, monospace;
+$graybox-border: 1px solid rgba(233, 233, 233, 1);
 
 html, body, div, span, h1, h3, h4, p, a, code, em, img, ul, li, table, tbody, tr, td {
   background: transparent;
@@ -102,6 +103,26 @@ html, body, div, span, h1, h3, h4, p, a, code, em, img, ul, li, table, tbody, tr
       display: inline-block;
     }
   }
+  dl {
+    border: $graybox-border;
+    @extend .para;
+    dt {
+      float: left;
+      width: 50px;
+      @extend em.term;
+      font-style: italic;
+      text-align: right;
+      padding: 7px;
+      vertical-align: top;
+    }
+    dd {
+      word-break: break-word;
+      margin-left: 64px;
+      padding: 7px;
+      min-width: 70px;
+      border-left: $graybox-border;
+    }
+  }
   .pointy-thing-container {
     background: #fff;
     border-bottom: 1px solid rgba(233, 233, 233, 1);
@@ -508,7 +529,7 @@ div.Swift {
 }
 
 .graybox {
-  border: 1px solid rgba(233, 233, 233, 1);
+  border: $graybox-border;
   border-collapse: collapse;
   border-spacing: 0;
   empty-cells: hide;
@@ -890,9 +911,9 @@ html.dash {
   }
   .chapter {
     border: none;
-    width: auto; 
-    position: static; 
-    padding-bottom: 50px; 
+    width: auto;
+    position: static;
+    padding-bottom: 50px;
     box-shadow: none;
   }
   #reference .chapter {

data/lib/jazzy/doc_builder.rb

@@ -52,9 +52,10 @@ module Jazzy
         if podspec = options.podspec
           stdout = PodspecDocumenter.new(podspec).sourcekitten_output
         else
-          stdout = SourceKitten.run_sourcekitten(
-            ['doc'] + options.xcodebuild_arguments,
-          )
+          stdout = Dir.chdir(Config.instance.source_directory) do
+            arguments = ['doc'] + options.xcodebuild_arguments
+            SourceKitten.run_sourcekitten(arguments)
+          end
         end
         unless $?.success?
           warn 'Please pass in xcodebuild arguments using -x'
@@ -276,9 +277,7 @@ module Jazzy
       doc[:name] = doc_model.name
       doc[:kind] = doc_model.type.name
       doc[:dash_type] = doc_model.type.dash_type
-      doc[:overview] = Jazzy.markdown.render(
-        (doc_model.abstract || '') + (doc_model.discussion || ''),
-      )
+      doc[:overview] = Jazzy.markdown.render(doc_model.overview)
       doc[:structure] = source_module.doc_structure
       doc[:tasks] = render_tasks(source_module, doc_model.children)
       doc[:module_name] = source_module.name

data/lib/jazzy/gem_version.rb

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

data/lib/jazzy/source_declaration.rb

@@ -18,5 +18,9 @@ module Jazzy
     attr_accessor :url
     attr_accessor :mark
     attr_accessor :access_control_level
+
+    def overview
+      "#{abstract}\n\n#{discussion}".strip
+    end
   end
 end

data/lib/jazzy/source_declaration/type.rb

@@ -31,10 +31,21 @@ module Jazzy
         kind == 'source.lang.swift.syntaxtype.comment.mark'
       end
 
+      def should_document?
+        declaration? && !param?
+      end
+
       def declaration?
         kind =~ /^source\.lang\.swift\.decl\..*/
       end
 
+      def param?
+        # SourceKit strangely categorizes initializer parameters as local
+        # variables, so both kinds represent a parameter in jazzy.
+        kind == 'source.lang.swift.decl.var.parameter' ||
+          kind == 'source.lang.swift.decl.var.local'
+      end
+
       def self.overview
         Type.new('Overview')
       end

data/lib/jazzy/sourcekitten.rb

@@ -38,13 +38,47 @@ 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
-          doc.url = parents.join('/') + '.html#/' + doc.usr
+          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 by filing an issue at ' \
+              'https://github.com/realm/jazzy/issues along with your Xcode ' \
+              'project.'
+          end
+          doc.url = parents.join('/') + '.html#/' + id
         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 Xcode 6.1 or 6.2 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.realpath : nil
+    end
+
+    def self.assert_swift_version
+      swift_version = `xcrun swift --version` =~ /Swift version ([\d\.]+)/ &&
+        Regexp.last_match[1]
+      expected_swift_version = '1.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
       bin_path = Pathname(__FILE__).parent + 'sourcekitten/sourcekitten'
       command = "#{bin_path} #{(arguments).join(' ')}"
       output = `#{command}`
@@ -78,7 +112,11 @@ module Jazzy
     end
 
     def self.process_undocumented_token(doc, declaration)
-      @undocumented_tokens << doc
+      source_directory = Config.instance.source_directory.to_s
+      filepath = doc['key.filepath']
+      if !filepath || filepath.start_with?(source_directory)
+        @undocumented_tokens << doc
+      end
       return nil if !documented_child?(doc) && @skip_undocumented
       make_default_doc_info(declaration)
     end
@@ -98,7 +136,6 @@ module Jazzy
       return nil unless should_document?(doc)
       xml_key = 'key.doc.full_as_xml'
       return process_undocumented_token(doc, declaration) unless doc[xml_key]
-      @documented_count += 1
 
       xml = Nokogiri::XML(doc[xml_key]).root
       declaration.line = XMLHelper.attribute(xml, 'line').to_i
@@ -111,7 +148,12 @@ module Jazzy
       declaration.discussion = XMLHelper.xpath(xml, 'Discussion')
       declaration.return = XMLHelper.xpath(xml, 'ResultDiscussion')
 
+      nodoc = ->(string) { string.to_s.include? '<dt>nodoc</dt>' }
+      return if nodoc[declaration.abstract] || nodoc[declaration.discussion]
+
       declaration.parameters = parameters_from_xml(xml)
+
+      @documented_count += 1
     end
 
     def self.make_substructure(doc, declaration)
@@ -139,12 +181,12 @@ module Jazzy
         if declaration.type.mark? && doc['key.name'].start_with?('MARK: ')
           current_mark = SourceMark.new(doc['key.name'])
         end
-        next unless declaration.type.declaration?
+        next unless declaration.type.should_document?
 
         unless declaration.type.name
-          raise 'Please file an issue on ' \
-          'https://github.com/realm/jazzy/issues about adding support for ' \
-          "`#{declaration.type.kind}`."
+          raise 'Please file an issue at ' \
+                'https://github.com/realm/jazzy/issues about adding support ' \
+                "for `#{declaration.type.kind}`."
         end
 
         declaration.file = doc['key.filepath']

data/spec/sourcekitten_spec.rb

@@ -0,0 +1,31 @@
+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 Xcode.*/Applications/Xcode.app}
+    end
+
+    it 'validates the current xcode version' do
+      SourceKitten.stubs(:`).returns <<-O
+Swift version 1.1 (swift-600.0.57.4)
+Target: x86_64-apple-darwin14.1.0
+      O
+      should.not.raise { SourceKitten.assert_swift_version }
+
+      SourceKitten.stubs(:`).returns <<-O
+Apple Swift version 1.2 (swiftlang-602.0.47.4 clang-602.0.48)
+Target: x86_64-apple-darwin14.1.0
+      O
+      should.raise { SourceKitten.assert_swift_version }.message.should
+        .match /Jazzy.*Swift 1\.1/
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,34 @@
+require 'rubygems'
+require 'bundler/setup'
+require 'bacon'
+require 'mocha-on-bacon'
+require 'pretty_bacon'
+require 'pathname'
+
+ROOT = Pathname.new(File.expand_path('../../', __FILE__))
+$LOAD_PATH.unshift((ROOT + 'lib').to_s)
+$LOAD_PATH.unshift((ROOT + 'spec').to_s)
+
+require 'jazzy'
+
+require 'spec_helper/pre_flight'
+
+Bacon.summary_at_exit
+
+module Bacon
+  class Context
+    include Jazzy::Config::Mixin
+
+    def temporary_directory
+      SpecHelper.temporary_directory
+    end
+  end
+end
+
+Mocha::Configuration.prevent(:stubbing_non_existent_method)
+
+module SpecHelper
+  def self.temporary_directory
+    ROOT + 'tmp'
+  end
+end

data/spec/spec_helper/pre_flight.rb

@@ -0,0 +1,21 @@
+# Restores the config to the default state before each requirement
+
+module Bacon
+  class Context
+    old_run_requirement = instance_method(:run_requirement)
+
+    define_method(:run_requirement) do |description, spec|
+      temporary_directory = SpecHelper.temporary_directory
+
+      ::Jazzy::Config.instance = nil
+      ::Jazzy::Config.instance.tap do |c|
+        c.source_directory = temporary_directory
+      end
+
+      temporary_directory.rmtree if temporary_directory.exist?
+      temporary_directory.mkpath
+
+      old_run_requirement.bind(self).call(description, spec)
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jazzy
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - JP Simard
@@ -10,7 +10,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-02-28 00:00:00.000000000 Z
+date: 2015-03-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mustache
@@ -243,6 +243,9 @@ files:
 - logo.sketch
 - screenshot.jpg
 - spec/integration_spec.rb
+- spec/sourcekitten_spec.rb
+- spec/spec_helper.rb
+- spec/spec_helper/pre_flight.rb
 homepage: http://github.com/realm/jazzy
 licenses:
 - MIT
@@ -263,7 +266,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.6
+rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
 summary: Soulful docs for Swift & Objective-C.