Skip to content
Browse files

Update docs

  • Loading branch information...
1 parent 5ead1d7 commit 80f8c873867b8896a0fb22faef9edc57c6f04bac @dudleyf dudleyf committed Feb 1, 2012
Showing with 72 additions and 70 deletions.
  1. +31 −31 README.yard
  2. +19 −21 lib/rake-pipeline/dsl/pipeline_dsl.rb
  3. +14 −9 lib/rake-pipeline/dsl/project_dsl.rb
  4. +8 −9 lib/rake-pipeline/project.rb
View
62 README.yard
@@ -6,42 +6,40 @@ output files based on input changes.
= Usage
-The easiest way to use Rake::Pipeline is via a +Assetfile+ file in the
+The easiest way to use Rake::Pipeline is via an +Assetfile+ file in the
root of your project.
A sample +Assetfile+ looks like this:
!!!ruby
- input "assets"
output "public"
- # this block will take all JS inputs, wrap them in a closure,
- # add some additional metadata, and concatenate them all into
- # application.scripts.js.
- match "*.js" do
- filter ClosureWrapper
- filter DataWrapper
- concat "application.scripts.js"
- end
+ input "assets" do
+ # this block will take all JS inputs, wrap them in a closure,
+ # add some additional metadata, and concatenate them all into
+ # application.scripts.js.
+ match "*.js" do
+ filter ClosureWrapper
+ filter DataWrapper
+ concat "application.scripts.js"
+ end
- # this block will take all HTML and CSS inputs, convert them
- # into JavaScript
- match "*/*.{html,css}" do
- filter DataWrapper
- concat "application.assets.js"
- end
+ # this block will take all HTML and CSS inputs, convert them
+ # into JavaScript
+ match "*/*.{html,css}" do
+ filter DataWrapper
+ concat "application.assets.js"
+ end
- match "*.js" do
- concat "application.js"
+ match "*.js" do
+ concat "application.js"
+ end
end
-The available options are:
-
-* {Rake::Pipeline::DSL#input input}: the directory containing your input files
-* {Rake::Pipeline::DSL#output output}: the directory to place your output files
- like to process
-* if you do not specify a block, the files will be
- copied over directly.
+Each +input+ block defines a collection of files, and a pipeline
+that transforms those files. Within each pipeline, you can specify
+a series of filters to describe the transformations you'd like to
+apply to the files.
= Filters
@@ -75,7 +73,7 @@ If you had a series of input files like:
* +app/javascripts/three.js+
and you specified the +ConcatFilter+ in your
-+AssetFile+ like:
++Assetfile+ like:
!!!ruby
filter ConcatFilter, "application.js"
@@ -106,15 +104,17 @@ This will stop `Rake::Pipeline` from trying to interpret the
input files as `UTF-8`, which obviously will not work on
binary data.
-= Built-In Filters
+= Filters
-At the current time, +Rake::Pipeline+ comes with a single built-in
-filter: {Rake::Pipeline::ConcatFilter}. Its implementation is
-the same as the `ConcatFilter` shown above.
++Rake::Pipeline+ comes with a built-in filter,
+{Rake::Pipeline::ConcatFilter}. Its implementation is the same as the
++ConcatFilter+ above. Other filters that are useful for web development
+like a +CoffeeScriptFilter+ and +SassFilter+ are available in
+[rake-pipeline-web-filters](https://github.com/wycats/rake-pipeline-web-filters).
= Preview Server
-To start up the preview server, run +rakep+. This will start up
+To start up the preview server, run +rakep server+. This will start up
a server that automatically recompiles files for you on the fly
and serves up the files you need.
View
40 lib/rake-pipeline/dsl/pipeline_dsl.rb
@@ -1,14 +1,11 @@
module Rake
class Pipeline
module DSL
- # This class exists purely to provide a convenient DSL for
+ # This class is used by {ProjectDSL} to provide a convenient DSL for
# configuring a pipeline.
#
# All instance methods of {PipelineDSL} are available in the context
# the block passed to +Rake::Pipeline.+{Pipeline.build}.
- #
- # When configuring a pipeline, you *must* provide both a
- # root, and a series of files using {#input}.
class PipelineDSL
# @return [Pipeline] the pipeline the DSL should configure
attr_reader :pipeline
@@ -35,19 +32,21 @@ def initialize(pipeline)
@pipeline = pipeline
end
- # Define the input location and files for the pipeline.
+ # Add an input location and files to a pipeline.
#
# @example
# !!!ruby
- # Rake::Pipeline.build do
- # input "app/assets", "**/*.js"
- # # ...
+ # Rake::Pipeline::Project.build do
+ # input "app" do
+ # input "assets", "**/*.js"
+ # # ...
+ # end
# end
#
# @param [String] root the root path where the pipeline
# should find its input files.
# @param [String] glob a file pattern that represents
- # the list of all files that the pipeline should
+ # the list of files that the pipeline should
# process within +root+. The default is +"**/*"+.
# @return [void]
def input(root, glob="**/*")
@@ -93,22 +92,21 @@ def filter(filter_class, *ctor_args, &block)
#
# @example
# !!!ruby
- # Pipeline.build do
- # input "app/assets"
+ # Rake::Pipeline::Project.build do
# output "public"
#
- # # compile coffee files into JS files
- # match "*.coffee" do
- # filter CompileCoffee do |input|
- # input.sub(/coffee$/, "js")
+ # input "app/assets" do
+ # # compile coffee files into JS files
+ # match "*.coffee" do
+ # coffee_script
# end
- # end
#
- # # because the previous step converted coffeee
- # # into JS, the coffee files will be included here
- # match "*.js" do
- # filter MinifyFilter
- # filter Rake::Pipeline::ConcatFilter, "application.js"
+ # # because the previous step converted coffeee
+ # # into JS, the coffee files will be included here
+ # match "*.js" do
+ # uglify
+ # concat "application.js"
+ # end
# end
# end
def match(pattern, &block)
View
23 lib/rake-pipeline/dsl/project_dsl.rb
@@ -2,13 +2,13 @@ module Rake
class Pipeline
module DSL
# This class exists purely to provide a convenient DSL for
- # configuring a pipeline.
+ # configuring a project.
#
- # All instance methods of {PipelineDSL} are available in the context
- # the block passed to +Rake::Pipeline.+{Pipeline.build}.
+ # All instance methods of {ProjectDSL} are available in the context
+ # the block passed to +Rake::Pipeline::Project.+{Project.build}.
#
- # When configuring a pipeline, you *must* provide both a
- # root, and a series of files using {#input}.
+ # When configuring a project, you *must* provide an output root
+ # and a series of files using at least one {#input} block.
class ProjectDSL
# @return [Project] the project the DSL should configure
attr_reader :project
@@ -35,18 +35,21 @@ def initialize(project)
end
# Specify the default output directory for the project.
- # Pipelines will place their outputs here unless they
- # set a different output in their {#input} block.
+ #
+ # Pipelines created in this project will place their
+ # outputs here unless the value is overriden in their
+ # {#input} block.
#
# @param [String] root the output directory.
# @return [void]
def output(root)
project.default_output_root = root
end
- # Specify the location of the temporary directory.
+ # Specify the location of the root temporary directory.
+ #
# Pipelines will store intermediate build artifacts
- # here.
+ # in a subdirectory of this directory.
#
# This defaults to "tmp" in the current working directory.
#
@@ -57,6 +60,8 @@ def tmpdir(root)
end
# Add a new pipeline with the given inputs to the project.
+ #
+ # @see Project.build_pipeline
def input(*inputs, &block)
project.build_pipeline(*inputs, &block)
end
View
17 lib/rake-pipeline/project.rb
@@ -9,7 +9,7 @@ class Project
# @return [Pipeline] the list of pipelines in the project
attr_reader :pipelines
- # @return [String|nil] the path to the {#project}'s Assetfile
+ # @return [String|nil] the path to the project's Assetfile
# or nil if it was created without an Assetfile.
attr_reader :assetfile_path
@@ -73,10 +73,9 @@ def add_to_digest(str)
end
end
- # @param [String|Rake::Pipeline] assetfile_or_pipeline
- # if this a String, create a Rake::Pipeline from the
- # Assetfile at that path. If it's a Rake::Pipeline,
- # just wrap that pipeline.
+ # @param [String|Pipeline] assetfile_or_pipeline
+ # if this a String, create a Pipeline from the Assetfile at
+ # that path. If it's a Pipeline, just wrap that pipeline.
def initialize(assetfile_or_pipeline=nil)
reset!
if assetfile_or_pipeline.kind_of?(String)
@@ -94,15 +93,15 @@ def build(&block)
self
end
- # Invoke the pipeline.
+ # Invoke all of the project's pipelines.
#
# @see Rake::Pipeline#invoke
def invoke
pipelines.each(&:invoke)
end
- # Invoke the pipeline, detecting any changes to the Assetfile
- # and rebuilding the pipeline if necessary.
+ # Invoke all of the project's pipelines, detecting any changes
+ # to the Assetfile and rebuilding the pipelines if necessary.
#
# @return [void]
# @see Rake::Pipeline#invoke_clean
@@ -118,7 +117,7 @@ def invoke_clean
end
end
- # Remove the pipeline's temporary and output files.
+ # Remove the project's temporary and output files.
def clean
files_to_clean.each { |file| FileUtils.rm_rf(file) }
end

0 comments on commit 80f8c87

Please sign in to comment.
Something went wrong with that request. Please try again.