jazzy 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: debc2610dfdacc28a580056ac62cfffdb0819402
-  data.tar.gz: 4a2d884071430d1581dbd971bd17ca43b51fa3df
+  metadata.gz: 4693be658ce9c28ddc98fdc398e26db8bc48d5c8
+  data.tar.gz: 2fd530bafb0099d145e8c07c2c34580f086aa79f
 SHA512:
-  metadata.gz: 4ef4bcac8aa9ec3a757ccd5c6b3c7b50fa5b29ca2b0e960e0084fa1233780af3605dc39064a51f516612afed4cca24b046e52bee09ae44bfb9bdf1865bf9ae77
-  data.tar.gz: f4a8965fc8c61270f9e156c431d0ad6ba600fc0c91f753c3964f3f9a5b8bbc8bacc3c0961987c8a5f899f75517f8e0c0f9163f505e97aac051745c95b6720c08
+  metadata.gz: ad9e58a8fd88262f1671ecd3394a970cd1d3a52f4a0b66798f64f0f77a715cae87702cea614ffc6bff235a026004d243bc699e1e33a9c7405a53040aaba29e0e
+  data.tar.gz: ee54d025fafa17e307eb2b2a9de639cc866a70ef799ce8ba1134130a93044c7d08c1ecd0a77504227f027e1e5b7327c2685be9ad363f7b91e5f4aa270c3ec216

data/DEV_README.md

@@ -0,0 +1,35 @@
+# Building jazzy
+
+jazzy is composed of two parts: the parser (written in C++) and the site generator (written in ruby). This guide will allow you to build both components.
+
+## 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`
+* [bundler](http://rubygems.org/gems/bundler)
+
+## Building ASTDump
+
+Unlike many other tools built using Clang, ASTDump doesn't require building the entirety of LLVM and Clang from source. Instead, ASTDump links against libclang, so builds take seconds, not hours.
+
+To build ASTDump, open `parser/ASTDump.xcodeproj` and hit `⌘+B`.
+
+Then, move the resulting ASTDump binary to `bin/ASTDump`. This will make it available to the site generator portion of jazzy.
+
+## Building & Running jazzy
+
+Run `bundle install` from the command line. This will install all the gems required to run jazzy.
+
+To run jazzy locally, use the following command: `ruby -Ilib bin/jazzy`. This instructs ruby to load the local `lib` directory, which will cause jazzy to find all its necessary file dependencies.
+
+To run jazzy on the sample input files located in `sample/`, run `ruby -Ilib bin/jazzy -i sample`. This will generate a `docs/` directory with the following structure:
+
+```
+docs/
+  CSS/
+  Images/
+  JAZMusician.html
+  JavaScript/
+```
+
+To run on any codebase, set the input argument (`-i`) to the directory containing your header files. i.e. `ruby -Ilib bin/jazzy -i /path/to/my/header/files`.

data/Gemfile

@@ -0,0 +1,11 @@
+source "http://rubygems.org"
+
+group :development do
+	gem "mustache", "~> 0.99.5"
+	gem "activesupport", "~> 4.1.1"
+	gem "redcarpet", "~> 3.1.2"
+	gem "nokogiri", "~> 1.6.2.1"
+
+	gem "bundler", "~> 1.5"
+	gem "rake"
+end

data/Gemfile.lock

@@ -0,0 +1,32 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    activesupport (4.1.4)
+      i18n (~> 0.6, >= 0.6.9)
+      json (~> 1.7, >= 1.7.7)
+      minitest (~> 5.1)
+      thread_safe (~> 0.1)
+      tzinfo (~> 1.1)
+    i18n (0.6.9)
+    json (1.8.1)
+    mini_portile (0.6.0)
+    minitest (5.3.5)
+    mustache (0.99.5)
+    nokogiri (1.6.2.1)
+      mini_portile (= 0.6.0)
+    rake (10.3.2)
+    redcarpet (3.1.2)
+    thread_safe (0.3.4)
+    tzinfo (1.2.1)
+      thread_safe (~> 0.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activesupport (~> 4.1.1)
+  bundler (~> 1.5)
+  mustache (~> 0.99.5)
+  nokogiri (~> 1.6.2.1)
+  rake
+  redcarpet (~> 3.1.2)

data/README.md

@@ -1,5 +1,5 @@
 ## jazzy <sup>♪♫</sup>
-**a soulful way to generate docs for Swift & Objective-C**
+**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.
 
@@ -7,9 +7,12 @@ Instead of parsing your source files, jazzy hooks into clang and uses the [AST][
 
 jazzy’s output matches the look & feel of Apple’s official reference documentation, post WWDC 2014.
 
+![Screenshot](screenshot.jpg)
+
 ### Requirements
 
-Jazzy requires [Xcode 6 Beta](https://developer.apple.com/xcode/) to run.
+* [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`
 
 ### Installing
 
@@ -19,31 +22,6 @@ To install jazzy, run `[sudo] gem install jazzy` from your command line.
 
 Run `jazzy` from your command line. Run `jazzy -h` for a list of additional options.
 
-### Front-End TODO
-
-- Index generation
-- Instance/class method distinction
-- Class inheritance, conforms, import, availability
-- Syntax Highlighting
-- Cross-linking
-- Search in page
-- Handle availability options
-- Inline code examples
-- Unit tests
-- Lists (unordered/ordered)
-- Generate docsets for Dash & Xcode
-- Pass in arbitrary Mustache templates
-
-### Parsing TODO
-
-- Swift files
-- `@name`
-- `@warning`
-- `@see`
-- Unit tests
-- Enum's
-- Instance variables
-
 ### Design Goals
 
 jazzy's main design goals are:
@@ -53,10 +31,10 @@ jazzy's main design goals are:
 - 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 [appldoc](https://github.com/tomaz/appledoc) when possible
+- Compatibility with [appledoc](https://github.com/tomaz/appledoc) when possible
 
 ### License
 
 This project is under the MIT license.
 
-[ast]: http://clang.llvm.org/docs/IntroductionToTheClangAST.html  "Introduction To The Clang AST"
+[ast]: http://clang.llvm.org/docs/IntroductionToTheClangAST.html "Introduction To The Clang AST"

data/bin/generate_swift_header.sh

@@ -0,0 +1,14 @@
+#!/bin/sh
+
+# Generate temporary swift module map
+header_file=$1
+module_name='TempJazzyModule'
+module_file='module.modulemap'
+echo "module $module_name { header \"$header_file\" }" > $module_file
+
+# Print generated Swift header
+# See also -req=interface-gen
+xcrun sourcekitd-test -req=doc-info -module $module_name -- -I `pwd` -sdk `xcrun --show-sdk-path`
+
+# Remove temporary module file
+rm $module_file

data/jazzy.gemspec

@@ -1,14 +1,14 @@
 # coding: utf-8
 
 module Jazzy
-  VERSION = '0.0.3'
+  VERSION = '0.0.4'
 end
 
 Gem::Specification.new do |spec|
   spec.name          = "jazzy"
   spec.version       = Jazzy::VERSION
   spec.authors       = ["JP Simard, Tim Anglade"]
-  spec.email         = ["jp@jpsim.com"]
+  spec.email         = ["jp@realm.io"]
   spec.summary       = %q{A soulful way to generate docs for Swift & Objective-C}
   spec.description   = %q{A soulful way to generate docs for Swift & Objective-C}
   spec.homepage      = "http://github.com/realm/jazzy"
@@ -24,4 +24,4 @@ Gem::Specification.new do |spec|
 
   spec.add_development_dependency "bundler", "~> 1.5"
   spec.add_development_dependency "rake"
-end
+end

data/lib/jazzy.rb

@@ -1,157 +1,150 @@
 class Jazzy
-	def self.headers(path)
-	  paths = []
-	  Find.find(path) do |path|
-	  	if (path =~ /.*\.h$/) and not (path =~ /.*private\.h$/i) and not (path =~ /test.*\//i)
-	    	paths << File.expand_path(path) 
-	    end
-	   end
-	  return paths
-	end
-
-	def self.document(path)
-		bin_path = File.expand_path(File.join( File.dirname(__FILE__),'../bin'))
-
-		klass = Jazzy::Klass.new
-
-		string = `#{bin_path}/SwiftHeader #{path}`
-		a = string.split(/^\[/); swift = a[0]; rawmap = "[\n"+a[-1]
-
-		rawmap.gsub!(/(key.\w+):/,'"\1":')
-		rawmap.gsub!(/(source..+),/,'"\1",')
-
-
-		xml = `#{bin_path}/ASTDump #{path}`
-
-		doc = Nokogiri::XML(xml)
-
-		results = doc.xpath("//*[@file='#{path}']")
-
-		#results = doc.find_all { |node| node.attribute("file") && node.attribute("file").strip.chomp == path.strip.chomp }
-		# Fill in Overview
-		top = results.first
-			#next if e.attribute("file") && e.attribute("file").text != path
-		#print top
-		#exit
-		klass[:name] = top.xpath("Name").text
-		klass[:usr] = top.xpath("USR").text
-		klass[:declaration] = {}
-		klass[:declaration][:objc] = top.xpath("Declaration").text.strip
-		klass[:abstract] = top.xpath("Abstract/Para").text.strip
-		paras = []; top.xpath("./Discussion/Para").each {|p| paras << p.text.strip }
-		klass[:discussion] = paras.join("\n\n")
-
-		# Only usable if Swift Header can be correctly generated
-		unless rawmap.include? "<<NULL>>"
-
-			swiftmap = {}
-			map = {}
-
-			JSON.parse(rawmap).each do |element|
-
-				next unless element["key.name"].downcase == klass[:name].downcase
-
-				# more than one matching element?
-
-				element["key.entities"].each do |e|
-					swiftmap[e["key.usr"]] = {}
-					swiftmap[e["key.usr"]]["declaration"] = swift.byteslice(e["key.offset"], e["key.length"])
-					swiftmap[e["key.usr"]]["name"] = e["key.name"]
-				end
-
-				# Inherits
-				klass[:inherits] = [] 
-				element["key.inherits"].each { |i| klass[:inherits] << { usr: i["key.usr"], name: i["key.name"] } } unless map["key.inherits"].nil?
-
-				# Conforms to
-				klass[:conforms] = []
-				element["key.conforms"].each { |c| klass[:conforms] << { usr: c["key.usr"], name: c["key.name"] } } unless map["key.conforms"].nil?
-			end
-		end
-
-
-
-
-		# Import
-		klass[:import] = swift.split("\n")[0].chomp.gsub('import ', '')
-		
-		# Fill in Properties
-		klass[:properties] = []
-
-		results[1..-1].each do |e|
-			next unless e.name == "Other"
-			property = {}
-			property[:usr] = e.xpath("USR").text
-			property[:name] = {}
-			property[:name][:objc] = e.xpath("Name").text
-			if !swiftmap.nil? && swiftmap[property[:usr]]
-				property[:name][:swift] = swiftmap[property[:usr]]["name"]
-			else
-				property[:name][:swift] = "Could not be generated"
-			end
-			property[:term] = property[:usr]
-			property[:declaration] = {}
-			property[:declaration][:objc] = e.xpath("Declaration").text.strip
-			if !swiftmap.nil? && swiftmap[property[:usr]]
-				property[:declaration][:swift] = swiftmap.nil?
-			else
-				property[:declaration][:swift] = "Could not be generated"
-			end
-			property[:abstract] = e.xpath("Abstract/Para").text.strip
-			paras = []; e.xpath("Discussion/Para").each {|p| paras << p.text.strip }
-			property[:discussion] = paras.join("\n\n") unless paras.length == 0
-			klass[:properties] << property
-		end
-
-		#puts klass[:properties]
-
-		# Fill in Methods
-		klass[:methods] = []
-		results[1..-1].each do |e|
-			next unless e.name == "Function"
-			method = {}
-			method[:usr] = e.xpath("USR").text
-			method[:name] = {}
-			method[:name][:objc] = e.xpath("Name").text
-			if !swiftmap.nil? && swiftmap[method[:usr]]
-				method[:name][:swift] = swiftmap[method[:usr]]["name"]
-			else
-				method[:name][:swift] = "Could not be generated"
-			end
-			next if method[:usr].include?('(py)')
-			method[:term] = method[:usr].split(')')[-1]
-			method[:declaration] = {}
-			method[:declaration][:objc] = e.xpath("Declaration").text
-			if !swiftmap.nil? && swiftmap[method[:usr]]
-				method[:declaration][:swift] = swiftmap[method[:usr]]["declaration"]
-			else
-				method[:declaration][:swift] = "Could not be generated"
-			end
-			method[:abstract] = e.xpath("Abstract/Para").text.strip
-			paras = []; e.xpath("Discussion/Para").each {|p| paras << p.text.strip }
-			method[:discussion] = paras.join("\n\n") unless paras.length == 0
-			method[:result] = e.xpath("ResultDiscussion/Para").text.strip
-
-			method[:parameters] = []
-			parameters = []; e.xpath("//Parameter").each do |p|
-				param = {}
-				param[:name] = p.xpath("Name").text
-				param[:discussion] = p.xpath("Discussion/Para").text.strip
-				method[:parameters] << param
-			end
-
-			klass[:methods] << method
-		end
-
-		klass.render
-	end
-
-	def self.assets(dir)
-		Dir.mkdir(File.join(dir,'CSS'))
-		Dir.mkdir(File.join(dir,'JavaScript'))
-		Dir.mkdir(File.join(dir,'Images'))
-		FileUtils.cp_r(Dir[File.expand_path(File.join( File.dirname(__FILE__),'assets/*'))],dir)
-	end
+
+  def self.headers(path)
+    paths = []
+    Find.find(path) do |path|
+      if (path =~ /.*\.h$/) && !(path =~ /.*private\.h$/i) && !(path =~ /test.*\//i)
+        paths << File.expand_path(path) 
+      end
+    end
+    paths
+  end
+
+  def self.document(path)
+    bin_path = File.expand_path(File.join(File.dirname(__FILE__), '../bin'))
+
+    klass = Jazzy::Klass.new
+
+    string = `#{bin_path}/generate_swift_header.sh #{path}`
+    a = string.split(/^\[/); swift = a[0]; rawmap = "[\n"+a[-1]
+
+    rawmap.gsub!(/(key.\w+):/,'"\1":')
+    rawmap.gsub!(/(source..+),/,'"\1",')
+
+    xml = `#{bin_path}/ASTDump #{path}`
+
+    doc = Nokogiri::XML(xml)
+
+    results = doc.xpath("//*[@file='#{path}']")
+
+    # Fill in Overview
+    top = results.first
+
+    klass[:name] = top.xpath("Name").text
+    klass[:usr] = top.xpath("USR").text
+    klass[:declaration] = {}
+    klass[:declaration][:objc] = top.xpath("Declaration").text.strip
+    klass[:abstract] = top.xpath("Abstract/Para").text.strip
+    paras = []; top.xpath("./Discussion/Para").each {|p| paras << p.text.strip }
+    klass[:discussion] = paras.join("\n\n")
+
+    # Only usable if Swift Header can be correctly generated
+    unless rawmap.include? "<<NULL>>"
+
+      swiftmap = {}
+      map = {}
+
+      JSON.parse(rawmap).each do |element|
+
+        next unless element["key.name"].downcase == klass[:name].downcase
+
+        # More than one matching element?
+        element["key.entities"].each do |e|
+          swiftmap[e["key.usr"]] = {}
+          swiftmap[e["key.usr"]]["declaration"] = swift.byteslice(e["key.offset"], e["key.length"])
+          swiftmap[e["key.usr"]]["name"] = e["key.name"]
+        end
+
+        # Inherits
+        klass[:inherits] = [] 
+        element["key.inherits"].each { |i| klass[:inherits] << { usr: i["key.usr"], name: i["key.name"] } } unless map["key.inherits"].nil?
+
+        # Conforms to
+        klass[:conforms] = []
+        element["key.conforms"].each { |c| klass[:conforms] << { usr: c["key.usr"], name: c["key.name"] } } unless map["key.conforms"].nil?
+      end
+    end
+
+    # Import
+    klass[:import] = swift.split("\n")[0].chomp.gsub('import ', '')
+
+    # Fill in Properties
+    klass[:properties] = []
+
+    results[1..-1].each do |e|
+      next unless e.name == "Other"
+      property = {}
+      property[:usr] = e.xpath("USR").text
+      property[:name] = {}
+      property[:name][:objc] = e.xpath("Name").text
+      if !swiftmap.nil? && swiftmap[property[:usr]]
+        property[:name][:swift] = swiftmap[property[:usr]]["name"]
+      else
+        property[:name][:swift] = "Could not be generated"
+      end
+      property[:term] = property[:usr]
+      property[:declaration] = {}
+      property[:declaration][:objc] = e.xpath("Declaration").text.strip
+      if !swiftmap.nil? && swiftmap[property[:usr]]
+        property[:declaration][:swift] = swiftmap.nil?
+      else
+        property[:declaration][:swift] = "Could not be generated"
+      end
+      property[:abstract] = e.xpath("Abstract/Para").text.strip
+      paras = []; e.xpath("Discussion/Para").each {|p| paras << p.text.strip }
+      property[:discussion] = paras.join("\n\n") unless paras.length == 0
+      klass[:properties] << property
+    end
+
+    #puts klass[:properties]
+
+    # Fill in Methods
+    klass[:methods] = []
+    results[1..-1].each do |e|
+      next unless e.name == "Function"
+      method = {}
+      method[:usr] = e.xpath("USR").text
+      method[:name] = {}
+      method[:name][:objc] = e.xpath("Name").text
+      if !swiftmap.nil? && swiftmap[method[:usr]]
+        method[:name][:swift] = swiftmap[method[:usr]]["name"]
+      else
+        method[:name][:swift] = "Could not be generated"
+      end
+      next if method[:usr].include?('(py)')
+      method[:term] = method[:usr].split(')')[-1]
+      method[:declaration] = {}
+      method[:declaration][:objc] = e.xpath("Declaration").text
+      if !swiftmap.nil? && swiftmap[method[:usr]]
+        method[:declaration][:swift] = swiftmap[method[:usr]]["declaration"]
+      else
+        method[:declaration][:swift] = "Could not be generated"
+      end
+      method[:abstract] = e.xpath("Abstract/Para").text.strip
+      paras = []; e.xpath("Discussion/Para").each {|p| paras << p.text.strip }
+      method[:discussion] = paras.join("\n\n") unless paras.length == 0
+      method[:result] = e.xpath("ResultDiscussion/Para").text.strip
+
+      method[:parameters] = []
+      parameters = []; e.xpath("//Parameter").each do |p|
+        param = {}
+        param[:name] = p.xpath("Name").text
+        param[:discussion] = p.xpath("Discussion/Para").text.strip
+        method[:parameters] << param
+      end
+
+      klass[:methods] << method
+    end
+
+    klass.render
+  end
+
+  def self.assets(dir)
+    Dir.mkdir(File.join(dir,'CSS'))
+    Dir.mkdir(File.join(dir,'JavaScript'))
+    Dir.mkdir(File.join(dir,'Images'))
+    FileUtils.cp_r(Dir[File.expand_path(File.join( File.dirname(__FILE__),'assets/*'))],dir)
+  end
 
 end