jazzy 0.0.20 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 3dad63dbae9be42cc3ddd0ca2947fe57b3d58ec4
-  data.tar.gz: 0529fe4cb24a3b5755ebc45dec7513e83065be23
+  metadata.gz: aff10a9b6fa27c5461c95ad82b50a0b736add8c3
+  data.tar.gz: 981592f5afab02d494657f83c4ec9c5cd4f02a1e
 SHA512:
-  metadata.gz: f0e5d10dc991a28b31ec80965358a53ea05c1ec4260eece4e4522d4cd042d47c9be90751a6b3077d18d589564848111af695df3999f6d6e1ecddfbdb49565eca
-  data.tar.gz: 40ec5dcd4b1c2f8b05cdcac3e4ecd3c95530309ecef088fc656271800996751078f5016d6ce6ee29bab25e39988153d911546e84991085a4b59af4e9fb260315
+  metadata.gz: f7fb5b838e6b0349e287d84af77199e6fd6d71b9c4f6b82ef586568749f18ff66c5366e7a071e8d50e140c354ab2780f66a04669fd129d6212010dfaa0d66141
+  data.tar.gz: 3f056e527f8abcbab57800ca4c3bace1c0f402bc5d615cc4f3a9f9998b225bb8befc8fded0b2ea4970aab062779459525def18d0b19593f756e86db9335ec56d

data/.gitmodules

@@ -1,3 +1,6 @@
-[submodule "spec/integration_specs/document_alamofire/before"]
-	path = spec/integration_specs/document_alamofire/before
-	url = https://github.com/Alamofire/Alamofire
+[submodule "SourceKitten"]
+	path = SourceKitten
+	url = https://github.com/jpsim/SourceKitten.git
+[submodule "spec/integration_specs"]
+	path = spec/integration_specs
+	url = https://github.com/Realm/jazzy-integration-specs.git

data/.travis.yml

@@ -6,7 +6,7 @@ rvm:
 
 before_install:
   - sudo gem install bundler
+  - git submodule update --init --recursive
 
 script:
   - bundle exec rake spec
-

data/CHANGELOG.md

@@ -1,6 +1,6 @@
 ## Master
 
-[sourcekitten](https://github.com/jpsim/sourcekitten/compare/0.2.7...master)
+[sourcekitten](https://github.com/jpsim/sourcekitten/compare/0.2.7...0.3.1)
 
 ##### Breaking
 
@@ -14,6 +14,28 @@
 
 * None.
 
+## 0.1.0
+
+[sourcekitten](https://github.com/jpsim/sourcekitten/compare/0.2.7...0.3.1)
+
+##### Breaking
+
+* None.
+
+##### Enhancements
+
+* Add the ability to document a Pod from just a podspec, which allows jazzy to
+  run on cocoadocs.org.  
+  [Samuel Giddins](https://github.com/segiddins)
+  [#58](https://github.com/realm/jazzy/issues/58)
+
+##### Bug Fixes
+
+* De-duplicate the sidebar list of extensions and show all children for an
+  extension, regardless of how many extensions on a type there are.  
+  [Samuel Giddins](https://github.com/segiddins)
+
+
 ## 0.0.20
 
 [sourcekitten](https://github.com/jpsim/sourcekitten/compare/0.2.6...0.2.7)

data/Gemfile.lock

@@ -1,8 +1,9 @@
 PATH
   remote: .
   specs:
-    jazzy (0.0.20)
+    jazzy (0.1.0)
       activesupport (~> 4.1)
+      cocoapods (~> 0.36.0.beta.2)
       mustache (~> 0.99)
       nokogiri (~> 1.6)
       redcarpet (~> 3.2)
@@ -24,25 +25,57 @@ GEM
     astrolabe (1.3.0)
       parser (>= 2.2.0.pre.3, < 3.0)
     bacon (1.2.0)
+    claide (0.8.0)
     clintegracon (0.5.3)
       colored (~> 1.2)
       diffy
+    cocoapods (0.36.0.beta.2)
+      activesupport (>= 3.2.15)
+      claide (~> 0.8.0)
+      cocoapods-core (= 0.36.0.beta.2)
+      cocoapods-downloader (~> 0.8.1)
+      cocoapods-plugins (~> 0.4.0)
+      cocoapods-trunk (~> 0.5.0)
+      cocoapods-try (~> 0.4.3)
+      colored (~> 1.2)
+      escape (~> 0.0.4)
+      molinillo (~> 0.2.0)
+      nap (~> 0.8)
+      open4 (~> 1.3)
+      xcodeproj (~> 0.21.2)
+    cocoapods-core (0.36.0.beta.2)
+      activesupport (>= 3.2.15)
+      fuzzy_match (~> 2.0.4)
+      nap (~> 0.8.0)
+    cocoapods-downloader (0.8.1)
+    cocoapods-plugins (0.4.0)
+      nap
+    cocoapods-trunk (0.5.0)
+      nap (>= 0.8)
+      netrc (= 0.7.8)
+    cocoapods-try (0.4.3)
     colored (1.2)
     crack (0.4.2)
       safe_yaml (~> 1.0.0)
     diffy (3.0.7)
+    escape (0.0.4)
+    fuzzy_match (2.0.4)
     i18n (0.7.0)
-    json (1.8.1)
+    json (1.8.2)
     metaclass (0.0.4)
     mini_portile (0.6.2)
-    minitest (5.5.0)
+    minitest (5.5.1)
     mocha (1.1.0)
       metaclass (~> 0.0.1)
     mocha-on-bacon (0.2.2)
       mocha (>= 0.13.0)
+    molinillo (0.2.0)
     mustache (0.99.8)
-    nokogiri (1.6.5)
+    nap (0.8.0)
+    netrc (0.7.8)
+    nokogiri (1.6.6.2)
       mini_portile (~> 0.6.0)
+    open4 (1.3.4)
     parser (2.2.0.pre.5)
       ast (>= 1.1, < 3.0)
       slop (~> 3.4, >= 3.4.5)
@@ -61,7 +94,7 @@ GEM
       ruby-progressbar (~> 1.4)
     ruby-progressbar (1.6.0)
     safe_yaml (1.0.4)
-    sass (3.4.9)
+    sass (3.4.10)
     slop (3.6.0)
     sqlite3 (1.3.10)
     thread_safe (0.3.4)
@@ -70,6 +103,9 @@ GEM
     webmock (1.20.0)
       addressable (>= 2.3.6)
       crack (>= 0.3.2)
+    xcodeproj (0.21.2)
+      activesupport (>= 3)
+      colored (~> 1.2)
 
 PLATFORMS
   ruby

data/Rakefile

@@ -5,6 +5,9 @@ task :bootstrap do
   if system('which bundle')
     title 'Installing gems'
     sh 'bundle install'
+
+    title 'Updating submodules'
+    sh 'git submodule update --init --recursive'
   else
     $stderr.puts "\033[0;31m" \
       "[!] Please install the bundler gem manually:\n" \
@@ -16,6 +19,7 @@ end
 
 begin
   require 'bundler/gem_tasks'
+  require 'fileutils'
 
   task default: :spec
 
@@ -69,6 +73,23 @@ begin
     task.patterns = %w(lib spec Rakefile Gemfile jazzy.gemspec)
   end
 
+  #-- SourceKitten -----------------------------------------------------------#
+
+  desc 'Vendors SourceKitten'
+  task :sourcekitten do
+    Dir.chdir('SourceKitten') do
+      `make installables`
+    end
+
+    destination = 'lib/jazzy/sourcekitten'
+    frameworks = Dir.glob('/tmp/SourceKitten.dst/Library/Frameworks/*')
+    binary = '/tmp/SourceKitten.dst/usr/local/bin/sourcekitten'
+    FileUtils.rm_rf destination
+    FileUtils.mkdir_p destination
+    FileUtils.cp_r frameworks, destination
+    FileUtils.cp binary, destination
+  end
+
 rescue LoadError, NameError
   $stderr.puts "\033[0;31m" \
     '[!] Some Rake tasks haven been disabled because the environment' \

data/jazzy.gemspec

@@ -24,6 +24,7 @@ Gem::Specification.new do |spec|
   spec.add_runtime_dependency 'sass', '~> 3.4'
   spec.add_runtime_dependency 'rouge', '~> 1.5'
   spec.add_runtime_dependency 'sqlite3', '~> 1.3'
+  spec.add_runtime_dependency 'cocoapods', '~> 0.36.0.beta.2'
 
   spec.add_development_dependency 'bundler', '~> 1.7'
   spec.add_development_dependency 'rake', '~> 10.3'

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

@@ -857,6 +857,12 @@ td {
 }
 
 html.dash {
+  body {
+    font-size: 65%;
+  }
+  a.Swift {
+    font-size: 110%;
+  }
   .book-parts {
     display: none;
     width: 0;
@@ -873,4 +879,24 @@ html.dash {
       margin-left: 0;
     }
   }
+  header, section#valence, .pixel-line, .rubber-band-gap {
+    display: none;
+  }
+  .content-wrapper {
+    width: auto;
+  }
+  .chapter {
+    border: none;
+    width: auto; 
+    position: static; 
+    padding-bottom: 50px; 
+    box-shadow: none;
+  }
+  #reference .chapter {
+    border: none;
+    box-shadow: none;
+  }
+  #footer {
+    position: static;
+  }
 }

data/lib/jazzy/config.rb

@@ -2,6 +2,7 @@ require 'optparse'
 require 'pathname'
 require 'uri'
 
+require 'jazzy/podspec_documenter'
 require 'jazzy/source_declaration/access_control_level'
 
 module Jazzy
@@ -23,8 +24,13 @@ module Jazzy
     attr_accessor :version
     attr_accessor :min_acl
     attr_accessor :skip_undocumented
+    attr_accessor :podspec
+    attr_accessor :docset_icon
+    attr_accessor :docset_path
+    attr_accessor :source_directory
 
     def initialize
+      PodspecDocumenter.configure(self, Dir['*.podspec{.json,}'].first)
       self.output = Pathname('docs')
       self.xcodebuild_arguments = []
       self.author_name = ''
@@ -35,6 +41,11 @@ module Jazzy
       self.version = '1.0'
       self.min_acl = SourceDeclaration::AccessControlLevel.internal
       self.skip_undocumented = false
+      self.source_directory = Pathname.pwd
+    end
+
+    def podspec=(podspec)
+      @podspec = PodspecDocumenter.configure(self, podspec)
     end
 
     # rubocop:disable Metrics/MethodLength
@@ -130,6 +141,24 @@ module Jazzy
           config.skip_undocumented = skip_undocumented
         end
 
+        opt.on('--podspec FILEPATH') do |podspec|
+          config.podspec = Pathname(podspec)
+        end
+
+        opt.on('--docset-icon FILEPATH') do |docset_icon|
+          config.docset_icon = Pathname(docset_icon)
+        end
+
+        opt.on('--docset-path DIRPATH', 'The relative path for the generated ' \
+               'docset') do |docset_path|
+          config.docset_path = docset_path
+        end
+
+        opt.on('--source-directory DIRPATH', 'The directory that contains ' \
+               'the source to be documented') do |source_directory|
+          config.source_directory = Pathname(source_directory)
+        end
+
         opt.on('-v', '--version', 'Print version number') do
           puts 'jazzy version: ' + Jazzy::VERSION
           exit

data/lib/jazzy/doc_builder.rb

@@ -8,6 +8,7 @@ require 'jazzy/config'
 require 'jazzy/doc'
 require 'jazzy/docset_builder'
 require 'jazzy/jazzy_markdown'
+require 'jazzy/podspec_documenter'
 require 'jazzy/readme_generator'
 require 'jazzy/source_declaration'
 require 'jazzy/source_module'
@@ -43,23 +44,27 @@ module Jazzy
 
     # Build documentation from the given options
     # @param [Config] options
+    # @return [SourceModule] the documented source module
     def self.build(options)
       if options.sourcekitten_sourcefile
-        file_contents = options.sourcekitten_sourcefile.read
-        build_docs_for_sourcekitten_output(file_contents, options)
+        stdout = options.sourcekitten_sourcefile.read
       else
-        stdout = SourceKitten.run_sourcekitten(options.xcodebuild_arguments)
-        exitstatus = $?.exitstatus
-        if exitstatus == 0
-          warn 'building site'
-          build_docs_for_sourcekitten_output(stdout, options)
+        if podspec = options.podspec
+          stdout = PodspecDocumenter.new(podspec).sourcekitten_output
         else
+          stdout = SourceKitten.run_sourcekitten(
+            ['doc'] + options.xcodebuild_arguments,
+          )
+        end
+        unless $?.success?
           warn 'Please pass in xcodebuild arguments using -x'
           warn 'If build arguments are correct, please file an issue on ' \
-          'https://github.com/realm/jazzy/issues'
-          exit exitstatus || 1
+            'https://github.com/realm/jazzy/issues'
+          exit $?.exitstatus || 1
         end
       end
+      warn 'building site'
+      build_docs_for_sourcekitten_output(stdout, options)
     end
 
     # Build & write HTML docs to disk from structured docs array
@@ -95,6 +100,7 @@ module Jazzy
     # Build docs given sourcekitten output
     # @param [String] sourcekitten_output Output of sourcekitten command
     # @param [Config] options Build options
+    # @return [SourceModule] the documented source module
     def self.build_docs_for_sourcekitten_output(sourcekitten_output, options)
       output_dir = options.output
       prepare_output_dir(output_dir, options.clean)
@@ -122,6 +128,8 @@ module Jazzy
       DocsetBuilder.new(output_dir, source_module).build!
 
       puts "jam out ♪♫ to your fresh new docs in `#{output_dir}`"
+
+      source_module
     end
 
     def self.decl_for_token(token)

data/lib/jazzy/docset_builder.rb

@@ -8,20 +8,24 @@ module Jazzy
       include Config::Mixin
 
       attr_reader :output_dir
+      attr_reader :generated_docs_dir
       attr_reader :source_module
       attr_reader :docset_dir
       attr_reader :documents_dir
 
-      def initialize(output_dir, source_module)
-        @output_dir = output_dir + 'docsets'
+      def initialize(generated_docs_dir, source_module)
         @source_module = source_module
-        @docset_dir = @output_dir + "#{source_module.name}.docset"
+        @docset_dir = generated_docs_dir +
+          (config.docset_path || "docsets/#{source_module.name}.docset")
+        @generated_docs_dir = generated_docs_dir
+        @output_dir = docset_dir.parent
         @documents_dir = docset_dir + 'Contents/Resources/Documents/'
       end
 
       def build!
         docset_dir.rmtree if docset_dir.exist?
         copy_docs
+        copy_icon if config.docset_icon
         write_plist
         create_index
         create_archive
@@ -54,12 +58,17 @@ module Jazzy
       end
 
       def copy_docs
-        files_to_copy = Dir.glob(output_dir + '../**/*')
+        files_to_copy = Pathname.glob(generated_docs_dir + '**/*') -
+          [docset_dir, output_dir]
 
         FileUtils.mkdir_p documents_dir
         FileUtils.cp_r files_to_copy, documents_dir
       end
 
+      def copy_icon
+        FileUtils.cp config.docset_icon, @docset_dir + 'icon.png'
+      end
+
       def create_index
         search_index_path = docset_dir + 'Contents/Resources/docSet.dsidx'
         SQLite3::Database.new(search_index_path.to_s) do |db|

data/lib/jazzy/gem_version.rb

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

data/lib/jazzy/jazzy_markdown.rb

@@ -29,7 +29,8 @@ module Jazzy
       no_intra_emphasis: true,
       quote: true,
       strikethrough: true,
-      space_after_headers: true,
+      space_after_headers: false,
+      tables: true,
     }.freeze
   end
 

data/lib/jazzy/podspec_documenter.rb

@@ -0,0 +1,109 @@
+require 'tmpdir'
+require 'json'
+
+module Jazzy
+  class PodspecDocumenter
+    attr_reader :podspec
+
+    def initialize(podspec)
+      @podspec = podspec
+    end
+
+    def sourcekitten_output
+      sandbox = Pod::Sandbox.new(pod_config.sandbox_root)
+      installer = Pod::Installer.new(sandbox, podfile)
+      installer.install!
+      stdout = Dir.chdir(sandbox.root) do
+        pod_targets.map do |t|
+          SourceKitten.run_sourcekitten(
+            %W(doc --module-name #{podspec.module_name} -target #{t}),
+          )
+        end
+      end
+      stdout.reduce([]) { |a, s| a + JSON.load(s) }.to_json
+    end
+
+    def self.configure(config, podspec)
+      case podspec
+      when Pathname, String
+        require 'cocoapods'
+        podspec = Pod::Specification.from_file(podspec)
+      end
+
+      return unless podspec
+
+      config.author_name = author_name(podspec)
+      config.module_name = podspec.module_name
+      config.author_url = podspec.homepage || github_file_prefix(podspec)
+      config.version = podspec.version.to_s
+      config.github_file_prefix = github_file_prefix(podspec)
+
+      podspec
+    end
+
+    private
+
+    # @!group Config helper methods
+
+    def self.author_name(podspec)
+      if podspec.authors.respond_to? :to_hash
+        podspec.authors.keys.to_sentence || ''
+      else
+        if podspec.authors.respond_to? :to_ary
+          podspec.authors.to_sentence
+        else
+          podspec.authors
+        end
+      end || ''
+    end
+
+    def self.github_file_prefix(podspec)
+      return unless podspec.source[:url] =~ %r{github.com[:/]+(.+)/(.+)}
+      org, repo = Regexp.last_match
+      return unless org && repo
+      repo.sub!(/\.git$/, '')
+      return unless rev = podspec.source[:tag] || podspec.source[:commit]
+      "https://github.com/#{org}/#{repo}/blob/#{rev}"
+    end
+
+    # @!group SourceKitten output helper methods
+
+    attr_reader :pod_targets
+
+    def pod_config
+      Pod::Config.instance.tap do |c|
+        c.installation_root = Pathname(Dir.mktmpdir)
+        c.installation_root.rmtree if c.installation_root.exist?
+        c.integrate_targets = false
+      end
+    end
+
+    def pod_path
+      if podspec.defined_in_file
+        podspec.defined_in_file.parent
+      else
+        config.source_directory
+      end
+    end
+
+    def podfile
+      podspec = @podspec
+      path = pod_path
+      targets = (@pod_targets ||= [])
+      @podfile ||= Pod::Podfile.new do
+        platform :ios, '8.0'
+        [podspec, *podspec.recursive_subspecs].each do |ss|
+          ss.available_platforms.each do |p|
+            t = "Jazzy-#{ss.name.gsub(/\//, '__')}-#{p.name}"
+            targets << "Pods-#{t}-#{ss.root.name}"
+            target(t) do
+              use_frameworks!
+              platform p.name, p.deployment_target
+              pod ss.name, path: path.realpath.to_s
+            end
+          end
+        end
+      end
+    end
+  end
+end