Major documentation refactoring

lib/cocoapods.rb

@@ -8,6 +8,7 @@ class Informative < StandardError
   autoload :Command,                'cocoapods/command'
   autoload :Config,                 'cocoapods/config'
   autoload :Dependency,             'cocoapods/dependency'
+  autoload :DocsGenerator,          'cocoapods/docs_generator'
   autoload :Downloader,             'cocoapods/downloader'
   autoload :Executable,             'cocoapods/executable'
   autoload :Installer,              'cocoapods/installer'

lib/cocoapods/command/install.rb

@@ -19,18 +19,14 @@ def self.banner
 
       def self.options
         "    --no-clean  Leave SCM dirs like `.git' and `.svn' in tact after downloading\n" +
+        "    --no-doc    Skip documentation generation with appledoc\n" +
         "    --no-update Skip running `pod repo update` before install\n" +
-        "    --no-doc    Skip documentation generation\n" +
-        "    --no-doc-force Generate documentation only for the pods that support it\n" +
-        "    --no-doc-install Skip documentation installation to Xcode\n" +
         super
       end
 
       def initialize(argv)
         config.clean = !argv.option('--no-clean')
         config.doc = !argv.option('--no-doc')
-        config.doc_install = !argv.option('--no-doc-install')
-        config.doc_force = !argv.option('--no-doc-force')
         @update_repo = !argv.option('--no-update')
         @projpath = argv.shift_argument
         super unless argv.empty?

lib/cocoapods/config.rb

@@ -10,13 +10,12 @@ def self.instance=(instance)
       @instance = instance
     end
 
-    attr_accessor :repos_dir, :project_root, :project_pods_root, :rootspec, :clean, :verbose, :silent, :doc, :doc_install, :doc_force
+    attr_accessor :repos_dir, :project_root, :project_pods_root, :rootspec, :clean, :verbose, :silent, :doc, :doc_install
     alias_method :clean?,       :clean
     alias_method :verbose?,     :verbose
     alias_method :silent?,      :silent
     alias_method :doc?,         :doc
     alias_method :doc_install?, :doc_install
-    alias_method :doc_force?,   :doc_force
 
     def initialize
       @repos_dir = Pathname.new(File.expand_path("~/.cocoapods"))
@@ -25,7 +24,6 @@ def initialize
       @silent = false
       @doc = true
       @doc_install = true
-      @doc_force = true
     end
 
     def project_root

lib/cocoapods/docs_generator.rb

@@ -0,0 +1,71 @@
+
+module Pod
+  class DocsGenerator
+    attr_reader :pod, :specification, :target_path, :options
+
+    def initialize(pod)
+      @pod = pod
+      @specification = pod.specification
+      @target_path = pod.sandbox.root + "Documentation" + pod.name
+      @options = pod.specification.documentation || {}
+    end
+
+    def appledoc (options)
+      bin = `which appledoc`.strip
+      if bin.empty?
+        return
+      end
+      arguments = []
+      arguments += options
+      arguments << '--print-settings' if Config.instance.verbose?
+      arguments += self.files
+      Open3.popen3('appledoc', *arguments) do |i, o, e|
+        if Config.instance.verbose?
+          puts o.read.chomp
+          puts e.read.chomp
+        else
+          # TODO: This is needed otherwise appledoc will not install the doc set
+          # This is a work around related to poor understanding of the IO class.
+          o.read
+          e.read
+        end
+      end
+    end
+
+    def generate_appledoc_options
+      project_company = @specification.authors ? @specification.authors.keys.join(', ') : 'no-company'
+      options = ['--project-name', @specification.to_s,
+                 '--project-company', project_company,
+                 '--docset-copyright', project_company,
+                 '--company-id', 'org.cocoapods',
+                 '--ignore', '.m']
+      options += ['--docset-desc', @specification.description] if @specification.description
+      ['README.md', 'README.mdown', 'README.markdown','README'].each do |f|
+        if File.file?(@pod.root + f)
+          options += ['--index-desc', f]
+          break
+        end
+      end
+      options += @options[:appledoc] if @options[:appledoc]
+      options
+
+    end
+
+    def files
+      @pod.absolute_source_files
+    end
+
+    def generate(install = false)
+      options = generate_appledoc_options
+      options += ['--output', @target_path]
+      options << '--keep-intermediate-files'
+      options << '--no-create-docset' unless install
+      @target_path.mkpath
+      @pod.chdir do
+        appledoc(options)
+      end
+    end
+
+  end
+end
+

lib/cocoapods/installer.rb

@@ -52,17 +52,16 @@ def install_dependencies!
             downloader = Downloader.for_pod(pod)
             downloader.download
 
-            if config.doc?
-              if pod.generate_documentation(config.doc_install?, config.doc_force? ,config.verbose?)
-                action = config.doc_install ? 'Installed' : 'Generated'
-                puts "-> #{action} documentation" unless config.silent?
-              end
-            end
-
             if config.clean
               downloader.clean
               pod.clean
             end
+
+            if config.doc?
+              puts "Installing Documentation for #{spec}" if config.verbose?
+              docs_generator = DocsGenerator.new(pod)
+              docs_generator.generate(config.doc_install?)
+            end
           end
         end
       end

lib/cocoapods/local_pod.rb

@@ -1,6 +1,7 @@
 module Pod
   class LocalPod
     attr_reader :specification
+    attr_reader :sandbox
 
     def initialize(specification, sandbox)
       @specification, @sandbox = specification, sandbox
@@ -51,6 +52,10 @@ def source_files
       expanded_paths(specification.source_files, :glob => '*.{h,m,mm,c,cpp}', :relative_to_sandbox => true)
     end
 
+    def absolute_source_files
+      expanded_paths(specification.source_files, :glob => '*.{h,m,mm,c,cpp}')
+    end
+
     def clean_paths
       expanded_paths(specification.clean_paths)
     end
@@ -74,50 +79,11 @@ def add_to_target(target)
         target.add_source_file(file, nil, specification.compiler_flags)
       end
     end
-
-    # Generates and installs the documentation of the pod.
-    #
-    # It returns true if the documentation was generated/installed
-    #
-    def generate_documentation(install, force = true, verbose = false)
-      documentation = specification.documentation ? specification.documentation : {}
-      success = false
-      if force || documentation.has_key?(:appledoc)
-        `which appledoc`
-        return nil unless $?.success?
-        dir = "#{@sandbox.root}/Documentation/#{name}/"
-        FileUtils.mkdir_p(dir)
-        # default options
-        #inline spec may not have some fields like authors
-        project_company = specification.authors ? specification.authors.keys.to_s : 'no-company-specified'
-        options = ['--project-name', specification.to_s,
-                   '--project-company', project_company,
-                   '--company-id', 'org.cocoapods',
-                   '--ignore', '.m']
-        options += ['--docset-copyright', "Generated by cocoapods (see #{specification.homepage} for copyright information)."] if specification.homepage
-        options += ['--docset-desc', specification.description] if specification.description
-        # spec options
-        options += documentation[:appledoc] if documentation[:appledoc]
-        # options that can't be overridden
-        options << '--no-create-docset' unless install
-        options << '--keep-intermediate-files'
-        options += ['--print-settings'] if verbose
-        options += ['--output', dir]
-        options += expanded_paths(specification.source_files, :glob => '*.{h,m,mm,c,cpp}', :relative_to_sandbox => false)
-        Open3.popen3('appledoc', *options ) do |stdin, stdout, stderr|
-          puts stdout.read.chomp if verbose
-          puts stderr.read.chomp if verbose
-          # TODO: success test should be more robust
-          success = stderr.read.chomp == ""
-        end
-      end
-      success
-    end
-
+
     def requires_arc?
       specification.requires_arc
     end
-
+    
     private
 
     def implementation_files
@@ -156,4 +122,3 @@ def expanded_paths(patterns, options={})
     end
   end
 end
-

spec/integration_spec.rb

@@ -39,6 +39,7 @@ def set.specification
         config.silent = true
         config.repos_dir = fixture('spec-repos')
         config.project_root = temporary_directory
+        config.doc_install = false
       end
 
       after do
@@ -127,6 +128,23 @@ def should_successfully_perform(command)
           change_log.should.include '1.2'
           change_log.should.not.include '1.3'
         end
+
+        it "generates documentation of all pods by default" do
+          podfile = Pod::Podfile.new do
+            self.platform :ios
+            dependency 'JSONKit', '1.4'
+            dependency 'SSToolkit'
+          end
+
+          installer = SpecHelper::Installer.new(podfile)
+          installer.install!
+
+          doc = (config.project_pods_root + 'Documentation/JSONKit/html/index.html').read
+          doc.should.include?('JSONKit (1.4)')
+
+          doc = (config.project_pods_root + 'Documentation/SSToolkit/html/index.html').read
+          doc.should.include?('SSToolkit')
+        end
       end
 
       before do

spec/unit/docs_generator_spec.rb

@@ -0,0 +1,53 @@
+require File.expand_path('../../spec_helper', __FILE__)
+
+
+describe Pod::DocsGenerator do
+
+  before do
+    @sandbox = temporary_sandbox
+    @pod = Pod::LocalPod.new(fixture_spec('banana-lib/BananaLib.podspec'), @sandbox)
+    copy_fixture_to_pod('banana-lib', @pod)
+    @doc_installer = Pod::DocsGenerator.new(@pod)
+    @doc_installer.generate
+  end
+
+  it 'returns reads correctly the Pod documentation' do
+    @doc_installer.options.should == {
+    :html => 'http://banana-corp.local/banana-lib/docs.html',
+    :appledoc => [
+       '--project-company', 'Banana Corp',
+       '--company-id', 'com.banana',
+    ]
+  }
+  end
+
+  it 'returns the Pod documentation documentation files' do
+    @doc_installer.files.sort.should == [
+      @pod.root + "Classes/Banana.m",
+      @pod.root + "Classes/Banana.h",
+    ].sort
+  end
+
+  it 'returns the Pod documentation options' do
+    @doc_installer.generate_appledoc_options.should == [
+      "--project-name", "BananaLib (1.0)",
+      "--project-company", "Monkey Boy, Banana Corp",
+      "--docset-copyright", "Monkey Boy, Banana Corp",
+      "--company-id", "org.cocoapods",
+      "--ignore", ".m",
+      "--docset-desc", "Full of chunky bananas.",
+      "--index-desc", "README",
+      "--project-company", "Banana Corp",
+      "--company-id", "com.banana"
+    ]
+  end
+
+  it 'it creates the documenation directory' do
+    File.directory?(@sandbox.root + "Documentation").should.be.true
+  end
+
+  it 'it creates the html' do
+    File.directory?(@sandbox.root + "Documentation/BananaLib/html").should.be.true
+  end
+end
+