jazzy 0.0.4 → 0.0.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4693be658ce9c28ddc98fdc398e26db8bc48d5c8
-  data.tar.gz: 2fd530bafb0099d145e8c07c2c34580f086aa79f
+  metadata.gz: e7a74dd62098862210aed5673baf188f364fbbaf
+  data.tar.gz: cc9531b73dfbdc5e02fd5f5489d9f81476a82394
 SHA512:
-  metadata.gz: ad9e58a8fd88262f1671ecd3394a970cd1d3a52f4a0b66798f64f0f77a715cae87702cea614ffc6bff235a026004d243bc699e1e33a9c7405a53040aaba29e0e
-  data.tar.gz: ee54d025fafa17e307eb2b2a9de639cc866a70ef799ce8ba1134130a93044c7d08c1ecd0a77504227f027e1e5b7327c2685be9ad363f7b91e5f4aa270c3ec216
+  metadata.gz: 725b86b39d1436252112d7c48ed599399dada85f77c0236e457c79cc0e6b10ea0fd1516b9b4a9ffebd171400e97279c2d64da402f344ad7334febdb8822e71fe
+  data.tar.gz: 2745f2aca3ce22c1ff821140736f10d7712b99ac996190ddd0545483140a4210e6f52befa84e84d2c74cb79044c00963f0ff3c71db491b38ba69e1f8793dbd8a

data/.gitignore

@@ -1,5 +1,5 @@
 jazzy-docs/
-docs/
+/docs/
 
 *.gem
 *.rbc
@@ -56,4 +56,4 @@ Icon
 .AppleDesktop
 Network Trash Folder
 Temporary Items
-.apdisk
+.apdisk

data/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "spec/integration_specs/document_alamofire/before"]
+	path = spec/integration_specs/document_alamofire/before
+	url = https://github.com/Alamofire/Alamofire

data/.rubocop.yml

@@ -0,0 +1,67 @@
+inherit_from:
+ - .rubocop_todo.yml
+
+AllCops:
+  Include:
+    - ./Rakefile
+    - ./Gemfile
+    - ./*.gemspec
+
+# At the moment not ready to be used
+# https://github.com/bbatsov/rubocop/issues/947
+Documentation:
+  Enabled: false
+
+#- Jazzy -----------------------------------------------------------------#
+
+# We adopted raise instead of fail.
+SignalException:
+  EnforcedStyle: only_raise
+
+# They are idiomatic
+AssignmentInCondition:
+  Enabled: false
+
+# Allow backticks
+AsciiComments:
+  Enabled: false
+
+# Indentation clarifies logic branches in implementations
+IfUnlessModifier:
+  Enabled: false
+
+# No enforced convention here.
+SingleLineBlockParams:
+  Enabled: false
+
+# We only add the comment when needed.
+Encoding:
+  Enabled: false
+
+# Having these make it easier to *not* forget to add one when adding a new
+# value and you can simply copy the previous line.
+TrailingComma:
+  EnforcedStyleForMultiline: comma
+
+Style/SpecialGlobalVars:
+  Enabled: false
+
+#- Jazzy specs -----------------------------------------------------------#
+
+# Allow for `should.match /regexp/`.
+AmbiguousRegexpLiteral:
+  Exclude:
+    - spec/**/*
+
+# Allow `object.should == object` syntax.
+Void:
+  Exclude:
+    - spec/**/*
+
+ClassAndModuleChildren:
+  Exclude:
+    - spec/**/*
+
+UselessComparison:
+  Exclude:
+    - spec/**/*

data/.rubocop_todo.yml

@@ -0,0 +1,16 @@
+# This configuration was generated by `rubocop --auto-gen-config`
+# on 2014-10-27 13:52:00 -0700 using RuboCop version 0.26.1.
+# The point is for the user to remove these configuration records
+# one by one as the offenses are removed from the code base.
+# Note that changes in the inspected code, or installation of new
+# versions of RuboCop, may require this file to be generated again.
+
+# Offense count: 19
+# Configuration parameters: AllowURI, URISchemes.
+Metrics/LineLength:
+  Max: 151
+
+# Offense count: 7
+# Configuration parameters: CountComments.
+Metrics/MethodLength:
+  Max: 50

data/.travis.yml

@@ -0,0 +1,6 @@
+os:
+  - osx
+language: ruby
+cache: bundler
+rvm:
+  - system

data/Gemfile

@@ -1,11 +1,19 @@
-source "http://rubygems.org"
+source 'http://rubygems.org'
+
+gemspec
 
 group :development do
-	gem "mustache", "~> 0.99.5"
-	gem "activesupport", "~> 4.1.1"
-	gem "redcarpet", "~> 3.1.2"
-	gem "nokogiri", "~> 1.6.2.1"
+  # Code style
+  gem 'rubocop'
+
+  # Tests
+  gem 'bacon'
+  gem 'mocha'
+  gem 'mocha-on-bacon'
+  gem 'prettybacon'
+  gem 'webmock'
 
-	gem "bundler", "~> 1.5"
-	gem "rake"
+  # Integration tests
+  gem 'diffy'
+  gem 'clintegracon'
 end

data/Gemfile.lock

@@ -1,32 +1,82 @@
+PATH
+  remote: .
+  specs:
+    jazzy (0.0.6)
+      activesupport (~> 4.1)
+      mustache (~> 0.99)
+      nokogiri (~> 1.6)
+      redcarpet (~> 3.2)
+
 GEM
   remote: http://rubygems.org/
   specs:
-    activesupport (4.1.4)
+    activesupport (4.1.6)
       i18n (~> 0.6, >= 0.6.9)
       json (~> 1.7, >= 1.7.7)
       minitest (~> 5.1)
       thread_safe (~> 0.1)
       tzinfo (~> 1.1)
+    addressable (2.3.6)
+    ast (2.0.0)
+    astrolabe (1.3.0)
+      parser (>= 2.2.0.pre.3, < 3.0)
+    bacon (1.2.0)
+    clintegracon (0.5.3)
+      colored (~> 1.2)
+      diffy
+    colored (1.2)
+    crack (0.4.2)
+      safe_yaml (~> 1.0.0)
+    diffy (3.0.7)
     i18n (0.6.9)
     json (1.8.1)
+    metaclass (0.0.4)
     mini_portile (0.6.0)
-    minitest (5.3.5)
-    mustache (0.99.5)
-    nokogiri (1.6.2.1)
+    minitest (5.4.2)
+    mocha (1.1.0)
+      metaclass (~> 0.0.1)
+    mocha-on-bacon (0.2.2)
+      mocha (>= 0.13.0)
+    mustache (0.99.7)
+    nokogiri (1.6.3.1)
       mini_portile (= 0.6.0)
+    parser (2.2.0.pre.5)
+      ast (>= 1.1, < 3.0)
+      slop (~> 3.4, >= 3.4.5)
+    powerpack (0.0.9)
+    prettybacon (0.0.2)
+      bacon (~> 1.2)
+    rainbow (2.0.0)
     rake (10.3.2)
-    redcarpet (3.1.2)
+    redcarpet (3.2.0)
+    rubocop (0.26.1)
+      astrolabe (~> 1.3)
+      parser (>= 2.2.0.pre.4, < 3.0)
+      powerpack (~> 0.0.6)
+      rainbow (>= 1.99.1, < 3.0)
+      ruby-progressbar (~> 1.4)
+    ruby-progressbar (1.6.0)
+    safe_yaml (1.0.4)
+    slop (3.6.0)
     thread_safe (0.3.4)
-    tzinfo (1.2.1)
+    tzinfo (1.2.2)
       thread_safe (~> 0.1)
+    webmock (1.20.0)
+      addressable (>= 2.3.6)
+      crack (>= 0.3.2)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  activesupport (~> 4.1.1)
-  bundler (~> 1.5)
-  mustache (~> 0.99.5)
-  nokogiri (~> 1.6.2.1)
-  rake
-  redcarpet (~> 3.1.2)
+  bacon
+  bundler (~> 1.7)
+  clintegracon
+  diffy
+  jazzy!
+  mocha
+  mocha-on-bacon
+  prettybacon
+  rake (~> 10.3)
+  rubocop
+  webmock

data/README.md

@@ -1,18 +1,27 @@
 ## jazzy <sup>♪♫</sup>
-**a soulful way to generate docs for Swift & Objective-C** ![analytics](https://ga-beacon.appspot.com/UA-50247013-2/jazzy/README?pixel)
+**a soulful way to generate docs for Swift & Objective-C**
+![analytics](https://ga-beacon.appspot.com/UA-50247013-2/jazzy/README?pixel)
 
-jazzy is a command-line utility that generates documentation for your Swift or Objective-C projects.
+jazzy is a command-line utility that generates documentation for your Swift or
+Objective-C projects.
 
-Instead of parsing your source files, jazzy hooks into clang and uses the [AST][ast] representation of your code and its comments for more accurate results.
+Only Swift projects are currently supported, but Objective-C support is coming
+soon!
 
-jazzy’s output matches the look & feel of Apple’s official reference documentation, post WWDC 2014.
+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.
+
+jazzy’s output matches the look & feel of Apple’s official reference
+documentation, post WWDC 2014.
 
 ![Screenshot](screenshot.jpg)
 
 ### Requirements
 
-* [Xcode 6 (Beta 2)](https://developer.apple.com/xcode)
-* `xcode-select -p` should print Xcode 6's path. If it doesn't, run `sudo xcode-select -s /Applications/Xcode6-Beta2.app/Contents/Developer`
+* [Xcode 6.1][xcode], installed in `/Applications/Xcode.app`
+* `xcode-select -p` should print Xcode 6.1's path. If it doesn't, run
+`sudo xcode-select -s /Applications/Xcode.app/Contents/Developer`
 
 ### Installing
 
@@ -20,21 +29,39 @@ To install jazzy, run `[sudo] gem install jazzy` from your command line.
 
 ### Usage
 
-Run `jazzy` from your command line. Run `jazzy -h` for a list of additional options.
+Run `jazzy` from your command line. Run `jazzy -h` for a list of additional
+options.
+
+### Development
+
+jazzy is composed of two parts: the parser ([sourcekitten][sourcekitten],
+written in Swift) and the site generator (written in ruby).
+
+To build and run jazzy from source, you'll first need [bundler][bundler]. Once
+bundler is installed, run `bundle install` from the root of this repo. At this
+point, run jazzy from source by running `bin/jazzy`.
+
+Instructions to build sourcekitten from source can be found at
+[sourcekitten's GitHub repository][sourcekitten].
 
 ### Design Goals
 
 jazzy's main design goals are:
 
 - Generate source code docs matching Apple's official reference documentation
-- Support for Xcode and Dash docsets
-- High readability of source code comments
-- Leverage modern HTML templating ([Mustache](http://mustache.github.io))
-- Leverage the power and accuracy of the [Clang AST][ast]
-- Compatibility with [appledoc](https://github.com/tomaz/appledoc) when possible
+- Support for standard Objective-C and Swift documentation comment syntax
+- Leverage modern HTML templating ([Mustache][mustache])
+- Leverage the power and accuracy of the [Clang AST][ast] and [SourceKit][sourcekit]
+- Support for Xcode and Dash docsets (*work in progress*)
+- Support Swift, Objective-C or mixed projects (*work in progress*)
 
 ### License
 
 This project is under the MIT license.
 
+[clang]: http://clang.llvm.org "Clang"
+[sourcekit]: http://www.jpsim.com/uncovering-sourcekit "Uncovering SourceKit"
 [ast]: http://clang.llvm.org/docs/IntroductionToTheClangAST.html "Introduction To The Clang AST"
+[xcode]: https://developer.apple.com/xcode "Xcode"
+[bundler]: http://rubygems.org/gems/bundler
+[mustache]: http://mustache.github.io "Mustache"

data/Rakefile

@@ -1 +1,87 @@
-require "bundler/gem_tasks"
+#-- Bootstrap --------------------------------------------------------------#
+
+desc 'Initializes your working copy to run the specs'
+task :bootstrap do
+  if system('which bundle')
+    title 'Installing gems'
+    sh 'bundle install'
+  else
+    $stderr.puts "\033[0;31m" \
+      "[!] Please install the bundler gem manually:\n" \
+      '    $ [sudo] gem install bundler' \
+      "\e[0m"
+    exit 1
+  end
+end
+
+begin
+  require 'bundler/gem_tasks'
+
+  task default: :spec
+
+  #-- Specs ------------------------------------------------------------------#
+
+  desc 'Run specs'
+  task :spec do
+    title 'Running Unit Tests'
+    files = FileList['spec/**/*_spec.rb'].shuffle.join(' ')
+    sh "bundle exec bacon #{files}"
+
+    Rake::Task['rubocop'].invoke
+  end
+
+  desc 'Rebuilds integration fixtures'
+  task :rebuild_integration_fixtures do
+    title 'Running Integration tests'
+    sh 'rm -rf spec/integration_specs/tmp'
+    puts `bundle exec bacon spec/integration_spec.rb`
+
+    title 'Storing fixtures'
+    # Copy the files to the files produced by the specs to the after folders
+    FileList['tmp/*'].each do |source|
+      destination = "spec/integration_specs/#{source.gsub('tmp/', '')}/after"
+      if File.exist?(destination)
+        sh "rm -rf #{destination}"
+        sh "mv #{source} #{destination}"
+      end
+    end
+
+    # Remove files not used for the comparison
+    # To keep the git diff clean
+    files_to_delete = FileList['spec/integration_specs/*/after/{*,.git,.gitignore}']
+      .exclude('spec/integration_specs/*/after/docs', 'spec/integration_specs/*/after/execution_output.txt')
+    files_to_delete.each do |file_to_delete|
+      sh "rm -rf '#{file_to_delete}'"
+    end
+
+    puts
+    puts 'Integration fixtures updated, see `spec/integration_specs`'
+  end
+
+  #-- RuboCop ----------------------------------------------------------------#
+
+  require 'rubocop/rake_task'
+  RuboCop::RakeTask.new(:rubocop) do |task|
+    task.patterns = %w(lib spec Rakefile Gemfile jazzy.gemspec)
+  end
+
+rescue LoadError, NameError
+  $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.' \
+    "\e[0m"
+  $stderr.puts e.message
+  $stderr.puts e.backtrace
+  $stderr.puts
+end
+
+#-- Helpers ------------------------------------------------------------------#
+
+def title(title)
+  cyan_title = "\033[0;36m#{title}\033[0m"
+  puts
+  puts '-' * 80
+  puts cyan_title
+  puts '-' * 80
+  puts
+end

data/bin/jazzy

@@ -1,49 +1,15 @@
 #!/usr/bin/env ruby
-require 'jazzy'
-require 'find'
-require 'fileutils'
-require 'optparse'
-
-options = {
-  input: File.expand_path('.'),
-  output: File.expand_path('docs'),
-  excludes: []
-}
-
-opt_parser = OptionParser.new do |opt|
-  opt.banner = "Usage: jazzy [-i input] [-o output]"
-  opt.separator  ""
-  opt.separator  "Options"
-
-  opt.on("-i","--input FOLDER","Folder to recursively search for header files") do |input|
-    options[:input] = File.expand_path(input)
-  end
-
-  opt.on("-o","--output FOLDER","Folder to output the HTML docs to") do |output|
-    options[:output] = File.expand_path(output)
-  end
-
-  opt.on("-e", "--exclude filepath1,filepath2,…filepathN", Array, "Exclude specific files") do |e|
-    options[:excludes] = e # path will be expanded after we’re sure the input has been stored
-  end
 
-  opt.on("-h","--help","help") do
-    puts opt_parser
-  end
+if $PROGRAM_NAME == __FILE__ && !ENV['JAZZY_NO_BUNDLER']
+  ENV['BUNDLE_GEMFILE'] = File.expand_path('../../Gemfile', __FILE__)
+  require 'rubygems'
+  require 'bundler/setup'
+  $LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+elsif ENV['JAZZY_NO_BUNDLER']
+  require 'rubygems'
+  gem 'jazzy'
 end
 
-opt_parser.parse!
-
-options[:excludes] = options[:excludes].map { |p| File.expand_path(File.join(options[:input], p)) }
-
-paths = Jazzy.headers(options[:input]) - options[:excludes]
-
-FileUtils.rm_r options[:output] if File.directory?(options[:output]); Dir.mkdir options[:output]
-
-paths.each do |path|
-  doc = Jazzy.document(path)
-  path = File.join(options[:output], path.scan(/\/(\w+)\.h$/)[0][0]+'.html')
-  File.open(path, 'w') { |file| file.write(doc) }                   
-end
+require 'jazzy'
 
-Jazzy.assets(options[:output])
+Jazzy::DocBuilder.build(Jazzy::Config.parse!)