[#149] Improved documentation generation

- refactoring
- default options for appledoc
- added command line arguments to pod install
- added option to force documentation generation with appledoc

lib/cocoapods/command.rb

@@ -69,8 +69,6 @@ module Pod
       show_help = argv.option('--help')
       Config.instance.silent = argv.option('--silent')
       Config.instance.verbose = argv.option('--verbose')
-      Config.instance.generate_documentation  = argv.option('--generate_documentation')
-      Config.instance.install_documentation  = argv.option('--install_documentation')
 
       command_class = case argv.shift_argument
       when 'install' then Install

lib/cocoapods/command/install.rb

@@ -20,11 +20,17 @@ module Pod
       def self.options
         "    --no-clean  Leave SCM dirs like `.git' and `.svn' in tact after downloading\n" +
         "    --no-update Skip running `pod repo update` before install\n" +
+        "    --doc-force Generate documentation for all pods with appledoc\n" +
+        "    --no-doc    Skip documentation generation\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('--doc-force')
         @update_repo = !argv.option('--no-update')
         @projpath = argv.shift_argument
         super unless argv.empty?

lib/cocoapods/config.rb

@@ -10,20 +10,22 @@ module Pod
       @instance = instance
     end
 
-    attr_accessor :repos_dir, :project_root, :project_pods_root, :rootspec, :clean, :verbose, :silent, :install_documentation, :generate_documentation
+    attr_accessor :repos_dir, :project_root, :project_pods_root, :rootspec, :clean, :verbose, :silent, :doc, :doc_install, :doc_force
     alias_method :clean?,       :clean
     alias_method :verbose?,     :verbose
     alias_method :silent?,      :silent
-    alias_method :install_documentation?,  :install_documentation
-    alias_method :generate_documentation?,  :generate_documentation
+    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"))
       @clean = true
       @verbose = false
       @silent = false
-      @install_documentation = false
-      @generate_documentation = false
+      @doc = true
+      @doc_install = true
+      @doc_force = false
     end
 
     def project_root

lib/cocoapods/installer.rb

@@ -51,13 +51,15 @@ module Pod
 
             downloader = Downloader.for_pod(pod)
             downloader.download
-            if config.generate_documentation && pod.can_generated_documentation
-              puts "Generating documentation for #{spec}" unless config.silent?
-              pods.each { |pod| pod.generate_documentation }
-            elsif config.install_documentation && pod.can_install_documentation
-              puts "Installing documentation for #{spec}" unless config.silent?
-              pods.each { |pod| pod.install_documentation }
+
+            if config.doc?
+              doc_source = pod.generate_documentation(config.doc_install?, config.doc_force? ,config.verbose?)
+              if doc_source
+                action = config.doc_install ? 'installed' : 'generated'
+                puts "           #{action} #{doc_source} documentation" unless config.silent?
+              end
             end
+
             if config.clean
               downloader.clean
               pod.clean

lib/cocoapods/local_pod.rb

@@ -75,40 +75,58 @@ module Pod
       end
     end
 
-    def can_generated_documentation
-      specification.documentation && specification.documentation[:appledoc]
-    end
-
-    def can_install_documentation
-      specification.documentation && specification.documentation[:appledoc]
-    end
-
-    def generate_documentation
-      if specification.documentation
-        appledoc_options = specification.documentation[:appledoc]
-        if appledoc_options
-          appledoc_options += ['--output', "#{@sandbox.root}/doc", '--no-create-docset']
-          appledoc_options += source_files
-          Open3.popen3('appledoc', *appledoc_options ) { |stdin, stdout, stderr|
-            puts stdout.read.chomp
-            puts stderr.read.chomp
-          }
-        end
-      end
-    end
-
-    def install_documentation
-      if specification.documentation
-        appledoc_options = specification.documentation[:appledoc]
-        if appledoc_options
-          appledoc_options += ['--output', "#{@sandbox.root}/doc"]
-          appledoc_options += source_files
-          Open3.popen3('appledoc', *appledoc_options ) { |stdin, stdout, stderr|
-            puts stdout.read.chomp
-            puts stderr.read.chomp
-          }
-        end
-      end
+    # Generates and installs the documentation of the pod.
+    #
+    # It returns a human redable string containing the source used
+    # for the documentation. If no source was available it returns
+    # nil.
+    #
+    def generate_documentation(install, force = true, verbose = false)
+      documentation = specification.documentation ? specification.documentation : {}
+
+      if force || documentation.has_key?(:appledoc)
+          `which appledoc`
+          return nil unless $?.success?
+          dir = "#{@sandbox.root}/Documentation/#{name}/"
+          FileUtils.mkdir_p(dir)
+          # default options
+          options = ['--project-name', specification.to_s,
+                      '--project-company', specification.authors.keys.to_s,
+                      '--docset-copyright', "Generated by cocoapods (see #{specification.homepage} for copyright information).",
+                      '--docset-desc', specification.description,
+                      '--company-id', 'org.cocoapods',
+                      '--ignore', '.m']
+          # 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 += ['--output', dir]
+          options += expanded_paths(specification.source_files, :glob => '*.{h,m,mm,c,cpp}', :relative_to_sandbox => false)
+          puts "appledoc #{options.join(" ")}" if verbose
+          success = false
+          Open3.popen3('appledoc', *options ) do |stdin, stdout, stderr|
+            puts stdout.read.chomp if verbose
+            puts stderr.read.chomp if verbose
+            success = stderr.read.chomp == ""
+          end
+          # TODO: should return nil if appledoc fails
+          return success ? 'appledoc' : nil
+
+        elsif documentation[:atom] && install
+          # TODO: donwload and uncompress the docset
+          # path =
+          #Open3.popen3('osascript') { |stdin, stdout, stderr|
+          #stdin.puts('tell application "Xcode"')
+          #stdin.puts("load documentation set with path \"#{path}\"")
+          #stdin.puts('end tell')
+          #stdin.close
+          #puts stdout.read.chomp if verbose
+          #puts stderr.read.chomp if verbose
+          #}
+          #return 'atom'
+        end
+      return nil
     end
 
     def requires_arc?