buildr-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From djspie...@apache.org
Subject svn commit: r912175 - in /buildr/trunk/lib/buildr: core/doc.rb java.rb java/compiler.rb java/doc.rb scala.rb scala/doc.rb
Date Sat, 20 Feb 2010 18:10:18 GMT
Author: djspiewak
Date: Sat Feb 20 18:10:17 2010
New Revision: 912175

URL: http://svn.apache.org/viewvc?rev=912175&view=rev
Log:
Created generic multi-language documentation framework

* Ported the javadoc task
* Added a scaladoc implementation

Added:
    buildr/trunk/lib/buildr/core/doc.rb
    buildr/trunk/lib/buildr/java/doc.rb
    buildr/trunk/lib/buildr/scala/doc.rb
Modified:
    buildr/trunk/lib/buildr/java.rb
    buildr/trunk/lib/buildr/java/compiler.rb
    buildr/trunk/lib/buildr/scala.rb

Added: buildr/trunk/lib/buildr/core/doc.rb
URL: http://svn.apache.org/viewvc/buildr/trunk/lib/buildr/core/doc.rb?rev=912175&view=auto
==============================================================================
--- buildr/trunk/lib/buildr/core/doc.rb (added)
+++ buildr/trunk/lib/buildr/core/doc.rb Sat Feb 20 18:10:17 2010
@@ -0,0 +1,248 @@
+module Buildr
+  module Doc
+    include Extension
+    
+    class << self
+      def select_by_lang(lang)
+        fail 'Unable to define doc task for nil language' if lang.nil?
+        engines.detect { |e| e.language.to_sym == lang.to_sym }
+      end
+      
+      alias_method :select, :select_by_lang
+      
+      def select_by_name(name)
+        fail 'Unable to define doc task for nil' if name.nil?
+        engines.detect { |e| e.to_sym == name.to_sym }
+      end
+      
+      def engines
+        @engines ||= []
+      end
+    end
+    
+    
+    # Base class for any documentation provider.  Defines most
+    # common functionality (things like @into@, @from@ and friends).
+    class Base
+      class << self
+        attr_accessor :language, :source_ext
+        
+        def specify(options)
+          @language = options[:language]
+          @source_ext = options[:source_ext]
+        end
+        
+        def to_sym
+          @symbol ||= name.split('::').last.downcase.to_sym
+        end
+      end
+      
+      attr_reader :project
+      
+      def initialize(project)
+        @project = project
+      end
+    end
+    
+    
+    class DocTask < Rake::Task
+      
+      # The target directory for the generated documentation files.
+      attr_reader :target
+
+      # Classpath dependencies.
+      attr_accessor :classpath
+
+      # Additional sourcepaths that are not part of the documented files.
+      attr_accessor :sourcepath
+        
+      # Returns the documentation tool options.
+      attr_reader :options
+      
+      # :nodoc:
+      attr_reader :project
+
+      def initialize(*args) #:nodoc:
+        super
+        @options = {}
+        @classpath = []
+        @sourcepath = []
+        @files = FileList[]
+        enhance do |task|
+          rm_rf target.to_s
+          mkdir_p target.to_s
+          
+          engine.generate(source_files, File.expand_path(target.to_s),
+            options.merge(:classpath => classpath, :sourcepath => sourcepath))
+          
+          touch target.to_s
+        end
+      end
+      
+      # :call-seq:
+      #   into(path) => self
+      #
+      # Sets the target directory and returns self. This will also set the Javadoc task
+      # as a prerequisite to a file task on the target directory.
+      #
+      # For example:
+      #   package :zip, :classifier=>'docs', :include=>doc.target
+      def into(path)
+        @target = file(path.to_s).enhance([self]) unless @target && @target.to_s
== path.to_s
+        self
+      end
+
+      # :call-seq:
+      #   include(*files) => self
+      #
+      # Includes additional source files and directories when generating the documentation
+      # and returns self. When specifying a directory, includes all source files in that
directory.
+      def include(*files)
+        @files.include *files.flatten.compact
+        self
+      end
+
+      # :call-seq:
+      #   exclude(*files) => self
+      #
+      # Excludes source files and directories from generating the documentation.
+      def exclude(*files)
+        @files.exclude *files
+        self
+      end
+
+      # :call-seq:
+      #   with(*artifacts) => self
+      #
+      # Adds files and artifacts as classpath dependencies, and returns self.
+      def with(*specs)
+        @classpath |= Buildr.artifacts(specs.flatten).uniq
+        self
+      end
+
+      # :call-seq:
+      #   using(options) => self
+      #
+      # Sets the documentation tool options from a hash and returns self.
+      #
+      # For example:
+      #   doc.using :windowtitle=>'My application'
+      #   doc.using :vscaladoc
+      def using(*args)
+        args.pop.each { |key, value| @options[key.to_sym] = value } if Hash === args.last
+        
+        until args.empty?
+          new_engine = doc.select_by_name(args.pop)
+          @engine = new_engine unless new_engine.nil?
+        end
+        
+        self
+      end
+      
+      def engine
+        @engine ||= guess_engine
+      end
+
+      # :call-seq:
+      #   from(*sources) => self
+      #
+      # Includes files, directories and projects in the documentation and returns self.
+      #
+      # You can call this method with source files and directories containing source files
+      # to include these files in the documentation, similar to #include. You can also call
+      # this method with projects. When called with a project, it includes all the source
files compiled
+      # by that project and classpath dependencies used when compiling.
+      #
+      # For example:
+      #   doc.from projects('myapp:foo', 'myapp:bar')
+      def from(*sources)
+        sources.flatten.each do |source|
+          case source
+          when Project
+            self.enhance source.prerequisites
+            self.include source.compile.sources
+            self.with source.compile.dependencies 
+          when Rake::Task, String
+            self.include source
+          else
+            fail "Don't know how to generate documentation from #{source || 'nil'}"
+          end
+        end
+        self
+      end
+
+      def prerequisites #:nodoc:
+        super + @files + classpath + sourcepath
+      end
+
+      def source_files #:nodoc:
+        @source_files ||= @files.map(&:to_s).map do |file|
+          File.directory?(file) ? FileList[File.join(file, "**/*.#{engine.class.source_ext}")]
: file 
+        end.flatten.reject { |file| @files.exclude?(file) }
+      end
+
+      def needed? #:nodoc:
+        return false if source_files.empty?
+        return true unless File.exist?(target.to_s)
+        source_files.map { |src| File.stat(src.to_s).mtime }.max > File.stat(target.to_s).mtime
+      end
+      
+    private
+    
+      def guess_engine
+        doc_engine = Doc.select project.compile.language
+        fail 'Unable to guess documentation provider for project.' unless doc_engine
+        doc_engine.new project
+      end
+      
+      def associate_with(project)
+        @project ||= project
+      end
+    end
+    
+    
+    first_time do
+      desc 'Create the documentation for this project'
+      Project.local_task :doc
+    end
+
+    before_define do |project|
+      DocTask.define_task('doc').tap do |doc|
+        doc.send(:associate_with, project)
+        doc.into project.path_to(:target, :doc)
+        doc.using :windowtitle=>project.comment || project.name
+      end
+    end
+
+    after_define do |project|
+      project.doc.from project
+    end
+
+    # :call-seq:
+    #   doc(*sources) => JavadocTask
+    #
+    # This method returns the project's documentation task. It also accepts a list of source
files,
+    # directories and projects to include when generating the docs.
+    #
+    # By default the doc task uses all the source directories from compile.sources and generates
+    # documentation in the target/doc directory. This method accepts sources and adds them
by calling
+    # Buildr::Doc::Base#from.
+    #
+    # For example, if you want to generate documentation for a given project that includes
all source files
+    # in two of its sub-projects:
+    #   doc projects('myapp:foo', 'myapp:bar').using(:windowtitle=>'Docs for foo and bar')
+    def doc(*sources, &block)
+      task('doc').from(*sources).enhance &block
+    end
+    
+    def javadoc(*sources, &block)
+      warn 'The javadoc method is deprecated and will be removed in a future release.'
+      doc(sources, block)
+    end
+  end
+  
+  
+  class Project
+    include Doc
+  end
+end

Modified: buildr/trunk/lib/buildr/java.rb
URL: http://svn.apache.org/viewvc/buildr/trunk/lib/buildr/java.rb?rev=912175&r1=912174&r2=912175&view=diff
==============================================================================
--- buildr/trunk/lib/buildr/java.rb (original)
+++ buildr/trunk/lib/buildr/java.rb Sat Feb 20 18:10:17 2010
@@ -20,4 +20,5 @@
 require 'buildr/java/bdd'
 require 'buildr/java/packaging'
 require 'buildr/java/commands'
+require 'buildr/java/doc'
 require 'buildr/java/deprecated'

Modified: buildr/trunk/lib/buildr/java/compiler.rb
URL: http://svn.apache.org/viewvc/buildr/trunk/lib/buildr/java/compiler.rb?rev=912175&r1=912174&r2=912175&view=diff
==============================================================================
--- buildr/trunk/lib/buildr/java/compiler.rb (original)
+++ buildr/trunk/lib/buildr/java/compiler.rb Sat Feb 20 18:10:17 2010
@@ -94,219 +94,6 @@
   end
 
 
-  # Methods added to Project for creating JavaDoc documentation.
-  module Javadoc
-
-    # A convenient task for creating Javadocs from the project's compile task. Minimizes
all
-    # the hard work to calling #from and #using.
-    #
-    # For example:
-    #   javadoc.from(projects('myapp:foo', 'myapp:bar')).using(:windowtitle=>'My App')
-    # Or, short and sweet:
-    #   desc 'My App'
-    #   define 'myapp' do
-    #     . . .
-    #     javadoc projects('myapp:foo', 'myapp:bar')
-    #   end
-    class JavadocTask < Rake::Task
-
-      def initialize(*args) #:nodoc:
-        super
-        @options = {}
-        @classpath = []
-        @sourcepath = []
-        @files = FileList[]
-        enhance do |task|
-          rm_rf target.to_s
-          generate source_files, File.expand_path(target.to_s), options.merge(:classpath=>classpath,
:sourcepath=>sourcepath)
-          touch target.to_s
-        end
-      end
-
-      # The target directory for the generated Javadoc files.
-      attr_reader :target
-
-      # :call-seq:
-      #   into(path) => self
-      #
-      # Sets the target directory and returns self. This will also set the Javadoc task
-      # as a prerequisite to a file task on the target directory.
-      #
-      # For example:
-      #   package :zip, :classifier=>'docs', :include=>javadoc.target
-      def into(path)
-        @target = file(path.to_s).enhance([self]) unless @target && @target.to_s
== path.to_s
-        self
-      end
-
-      # :call-seq:
-      #   include(*files) => self
-      #
-      # Includes additional source files and directories when generating the documentation
-      # and returns self. When specifying a directory, includes all .java files in that directory.
-      def include(*files)
-        @files.include *files.flatten.compact
-        self
-      end
-
-      # :call-seq:
-      #   exclude(*files) => self
-      #
-      # Excludes source files and directories from generating the documentation.
-      def exclude(*files)
-        @files.exclude *files
-        self
-      end
-
-      # Classpath dependencies.
-      attr_accessor :classpath
-
-      # :call-seq:
-      #   with(*artifacts) => self
-      #
-      # Adds files and artifacts as classpath dependencies, and returns self.
-      def with(*specs)
-        @classpath |= Buildr.artifacts(specs.flatten).uniq
-        self
-      end
-
-      # Additional sourcepaths that are not part of the documented files.
-      attr_accessor :sourcepath
-        
-      # Returns the Javadoc options.
-      attr_reader :options
-
-      # :call-seq:
-      #   using(options) => self
-      #
-      # Sets the Javadoc options from a hash and returns self.
-      #
-      # For example:
-      #   javadoc.using :windowtitle=>'My application'
-      def using(*args)
-        args.pop.each { |key, value| @options[key.to_sym] = value } if Hash === args.last
-        args.each { |key| @options[key.to_sym] = true }
-        self
-      end
-
-      # :call-seq:
-      #   from(*sources) => self
-      #
-      # Includes files, directories and projects in the Javadoc documentation and returns
self.
-      #
-      # You can call this method with Java source files and directories containing Java source
files
-      # to include these files in the Javadoc documentation, similar to #include. You can
also call
-      # this method with projects. When called with a project, it includes all the source
files compiled
-      # by that project and classpath dependencies used when compiling.
-      #
-      # For example:
-      #   javadoc.from projects('myapp:foo', 'myapp:bar')
-      def from(*sources)
-        sources.flatten.each do |source|
-          case source
-          when Project
-            self.enhance source.prerequisites
-            self.include source.compile.sources
-            self.with source.compile.dependencies 
-          when Rake::Task, String
-            self.include source
-          else
-            fail "Don't know how to generate Javadocs from #{source || 'nil'}"
-          end
-        end
-        self
-      end
-
-      def prerequisites() #:nodoc:
-        super + @files + classpath + sourcepath
-      end
-
-      def source_files() #:nodoc:
-        @source_files ||= @files.map(&:to_s).
-          map { |file| File.directory?(file) ? FileList[File.join(file, "**/*.java")] : file
}.
-          flatten.reject { |file| @files.exclude?(file) }
-      end
-
-      def needed?() #:nodoc:
-        return false if source_files.empty?
-        return true unless File.exist?(target.to_s)
-        source_files.map { |src| File.stat(src.to_s).mtime }.max > File.stat(target.to_s).mtime
-      end
-
-    private
-
-      def generate(sources, target, options = {})
-        cmd_args = [ '-d', target, Buildr.application.options.trace ? '-verbose' : '-quiet'
]
-        options.reject { |key, value| [:sourcepath, :classpath].include?(key) }.
-          each { |key, value| value.invoke if value.respond_to?(:invoke) }.
-          each do |key, value|
-            case value
-            when true, nil
-              cmd_args << "-#{key}"
-            when false
-              cmd_args << "-no#{key}"
-            when Hash
-              value.each { |k,v| cmd_args << "-#{key}" << k.to_s << v.to_s
}
-            else
-              cmd_args += Array(value).map { |item| ["-#{key}", item.to_s] }.flatten
-            end
-          end
-        [:sourcepath, :classpath].each do |option|
-          Array(options[option]).flatten.tap do |paths|
-            cmd_args << "-#{option}" << paths.flatten.map(&:to_s).join(File::PATH_SEPARATOR)
unless paths.empty?
-          end
-        end
-        cmd_args += sources.flatten.uniq
-        unless Buildr.application.options.dryrun
-          info "Generating Javadoc for #{name}"
-          trace (['javadoc'] + cmd_args).join(' ')
-          Java.load
-          Java.com.sun.tools.javadoc.Main.execute(cmd_args.to_java(Java.java.lang.String))
== 0 or
-            fail 'Failed to generate Javadocs, see errors above'
-        end
-      end
-
-    end
-
-
-    include Extension
-
-    first_time do
-      desc 'Create the Javadocs for this project'
-      Project.local_task('javadoc')
-    end
-
-    before_define(:javadoc) do |project|
-      JavadocTask.define_task('javadoc').tap do |javadoc|
-        javadoc.into project.path_to(:target, :javadoc)
-        javadoc.using :windowtitle=>project.comment || project.name
-      end
-    end
-
-    after_define(:javadoc) do |project|
-      project.javadoc.from project
-    end
-
-    # :call-seq:
-    #   javadoc(*sources) => JavadocTask
-    #
-    # This method returns the project's Javadoc task. It also accepts a list of source files,
-    # directories and projects to include when generating the Javadocs.
-    #
-    # By default the Javadoc task uses all the source directories from compile.sources and
generates
-    # Javadocs in the target/javadoc directory. This method accepts sources and adds them
by calling
-    # JavadocsTask#from.
-    #
-    # For example, if you want to generate Javadocs for a given project that includes all
source files
-    # in two of its sub-projects:
-    #   javadoc projects('myapp:foo', 'myapp:bar').using(:windowtitle=>'Docs for foo and
bar')
-    def javadoc(*sources, &block)
-      task('javadoc').from(*sources).enhance &block
-    end
-
-  end
-
-
   # Methods added to Project to support the Java Annotation Processor.
   module Apt
 
@@ -344,6 +131,5 @@
 
 Buildr::Compiler << Buildr::Compiler::Javac
 class Buildr::Project
-  include Buildr::Javadoc
   include Buildr::Apt
 end

Added: buildr/trunk/lib/buildr/java/doc.rb
URL: http://svn.apache.org/viewvc/buildr/trunk/lib/buildr/java/doc.rb?rev=912175&view=auto
==============================================================================
--- buildr/trunk/lib/buildr/java/doc.rb (added)
+++ buildr/trunk/lib/buildr/java/doc.rb Sat Feb 20 18:10:17 2010
@@ -0,0 +1,55 @@
+require 'buildr/core/doc'
+
+module Buildr
+  module Doc
+
+    # A convenient task for creating Javadocs from the project's compile task. Minimizes
all
+    # the hard work to calling #from and #using.
+    #
+    # For example:
+    #   doc.from(projects('myapp:foo', 'myapp:bar')).using(:windowtitle=>'My App')
+    # Or, short and sweet:
+    #   desc 'My App'
+    #   define 'myapp' do
+    #     . . .
+    #     doc projects('myapp:foo', 'myapp:bar')
+    #   end
+    class Javadoc < Base
+      
+      specify :language => :java, :source_ext => 'java'
+      
+      def generate(sources, target, options = {})
+        cmd_args = [ '-d', target, Buildr.application.options.trace ? '-verbose' : '-quiet'
]
+        options.reject { |key, value| [:sourcepath, :classpath].include?(key) }.
+          each { |key, value| value.invoke if value.respond_to?(:invoke) }.
+          each do |key, value|
+            case value
+            when true, nil
+              cmd_args << "-#{key}"
+            when false
+              cmd_args << "-no#{key}"
+            when Hash
+              value.each { |k,v| cmd_args << "-#{key}" << k.to_s << v.to_s
}
+            else
+              cmd_args += Array(value).map { |item| ["-#{key}", item.to_s] }.flatten
+            end
+          end
+        [:sourcepath, :classpath].each do |option|
+          Array(options[option]).flatten.tap do |paths|
+            cmd_args << "-#{option}" << paths.flatten.map(&:to_s).join(File::PATH_SEPARATOR)
unless paths.empty?
+          end
+        end
+        cmd_args += sources.flatten.uniq
+        unless Buildr.application.options.dryrun
+          info "Generating Javadoc for #{project.name}"
+          trace (['javadoc'] + cmd_args).join(' ')
+          Java.load
+          Java.com.sun.tools.javadoc.Main.execute(cmd_args.to_java(Java.java.lang.String))
== 0 or
+            fail 'Failed to generate Javadocs, see errors above'
+        end
+      end
+    end
+  end
+end
+
+Buildr::Doc.engines << Buildr::Doc::Javadoc

Modified: buildr/trunk/lib/buildr/scala.rb
URL: http://svn.apache.org/viewvc/buildr/trunk/lib/buildr/scala.rb?rev=912175&r1=912174&r2=912175&view=diff
==============================================================================
--- buildr/trunk/lib/buildr/scala.rb (original)
+++ buildr/trunk/lib/buildr/scala.rb Sat Feb 20 18:10:17 2010
@@ -20,6 +20,7 @@
 require 'buildr/scala/compiler'
 require 'buildr/scala/tests'
 require 'buildr/scala/bdd'
+require 'buildr/scala/doc'
 require 'buildr/scala/shell'
 
 Object::Scala = Buildr::Scala

Added: buildr/trunk/lib/buildr/scala/doc.rb
URL: http://svn.apache.org/viewvc/buildr/trunk/lib/buildr/scala/doc.rb?rev=912175&view=auto
==============================================================================
--- buildr/trunk/lib/buildr/scala/doc.rb (added)
+++ buildr/trunk/lib/buildr/scala/doc.rb Sat Feb 20 18:10:17 2010
@@ -0,0 +1,43 @@
+require 'buildr/core/doc'
+require 'buildr/scala/compiler'   # ensure Scala dependencies are ready
+
+module Buildr
+  module Doc
+    class Scaladoc < Base
+      specify :language => :scala, :source_ext => 'scala'
+      
+      def generate(sources, target, options = {})
+        cmd_args = [ '-d', target, Buildr.application.options.trace ? '-verbose' : '' ]
+        options.reject { |key, value| [:sourcepath, :classpath].include?(key) }.
+          each { |key, value| value.invoke if value.respond_to?(:invoke) }.
+          each do |key, value|
+            case value
+            when true, nil
+              cmd_args << "-#{key}"
+            when false
+              cmd_args << "-no#{key}"
+            when Hash
+              value.each { |k,v| cmd_args << "-#{key}" << k.to_s << v.to_s
}
+            else
+              cmd_args += Array(value).map { |item| ["-#{key}", item.to_s] }.flatten
+            end
+          end
+        [:sourcepath, :classpath].each do |option|
+          Array(options[option]).flatten.tap do |paths|
+            cmd_args << "-#{option}" << paths.flatten.map(&:to_s).join(File::PATH_SEPARATOR)
unless paths.empty?
+          end
+        end
+        cmd_args += sources.flatten.uniq
+        unless Buildr.application.options.dryrun
+          info "Generating Scaladoc for #{project.name}"
+          trace (['scaladoc'] + cmd_args).join(' ')
+          Java.load
+          Java.scala.tools.nsc.ScalaDoc.main(cmd_args.to_java(Java.java.lang.String)) ==
0 or
+            fail 'Failed to generate Scaladocs, see errors above'
+        end
+      end
+    end
+  end
+end
+
+Buildr::Doc.engines << Buildr::Doc::Scaladoc



Mime
View raw message