rsync.rb in nanoc3-3.1.0a3

- old
+ new

@@ -1,12 +1,13 @@
 # encoding: utf-8
 
 module Nanoc3::Extra::Deployers
 
-  # Nanoc3::Extra::Deployers::Rsync is a deployer that deploys a site using rsync.
+  # A deployer that deploys a site using rsync.
   class Rsync
 
+    # Default rsync options
     DEFAULT_OPTIONS = [
       '-glpPrtvz',
       '--exclude=".hg"',
       '--exclude=".svn"',
       '--exclude=".git"'
@@ -17,56 +18,58 @@
     # to be the current working directory).
     #
     # The deployment configurations are stored like this in the site's
     # configuration file:
     #
-    #     deploy:
-    #       NAME:
-    #         options: [ OPTIONS ]
-    #         dst:     "DST"
+    #   deploy:
+    #     NAME:
+    #       options: [ OPTIONS ]
+    #       dst:     "DST"
     #
-    # +NAME+ is a unique name for the deployment configuration. By default,
-    # the deployer will use the deployment configuration named "default".
+    # `NAME` is a unique name for the deployment configuration. By default,
+    # the deployer will use the deployment configuration named `"default"`.
     #
-    # +OPTIONS+ is an array containing options to pass to the rsync
-    # executable. This is not required; by default, +-glpPrtvz+ and
-    # +--exclude+s for +.svn+, +.hg+ and +.git+ are used.
+    # `OPTIONS` is an array containing options to pass to the rsync
+    # executable. This is not required; by default, {DEFAULT_OPTIONS} options
+    # will be used.
     #
-    # +DST+ is a string containing the destination to where rsync should
-    # upload its data. It will likely be in +host:path+ format. For example,
-    # "example.com:/var/www/sites/mysite/html". It should not end with a
+    # `DST` is a string containing the destination to where rsync should
+    # upload its data. It will likely be in `host:path` format. For example,
+    # `"example.com:/var/www/sites/mysite/html"`. It should not end with a
     # trailing slash.
     #
     # Example: This deployment configuration defines a "default" and a
     # "staging" deployment configuration. The default options are used.
     #
-    #     deploy:
-    #       default:
-    #         dst: "ectype:sites/stoneship/public"
-    #       staging:
-    #         dst: "ectype:sites/stoneship-staging/public"
-    #         options: [ "-glpPrtvz" ]
+    #   deploy:
+    #     default:
+    #       dst: "ectype:sites/stoneship/public"
+    #     staging:
+    #       dst: "ectype:sites/stoneship-staging/public"
+    #       options: [ "-glpPrtvz" ]
     #
-    # When running the deployer with the "default" resp. "staging"
+    # When running the deployer with the `default` resp. `staging`
     # configurations, the following rsync commands will be executed:
     #
-    #     rsync -glpPrtvz --exclude=".hg" --exclude=".svn"
-    #       --exclude=".git" output ectype:sites/stoneship/public
+    #   rsync -glpPrtvz --exclude=".hg" --exclude=".svn"
+    #     --exclude=".git" output ectype:sites/stoneship/public
     #
-    #     rsync -glpPrtvz output ectype:sites/stoneship-staging/public
+    #   rsync -glpPrtvz output ectype:sites/stoneship-staging/public
     def initialize
       # Get site
       error 'No site configuration found' unless File.file?('config.yaml')
       @site = Nanoc3::Site.new('.')
     end
 
     # Runs the task. Possible params:
     #
-    # +:dry_run+:: Set to true when the action itself should not be executed,
-    #              but still printed. Useful for debugging.
+    # @option params [Boolean] :dry_run (false) True if the action itself
+    # should not be executed, but still printed; false otherwise.
     #
-    # +:config_name+:: The name of the deployment configuration to use.
-    #                  Defaults to +:default+ (surprise!).
+    # @option params [String] :config_name (:default) The name of the
+    # deployment configuration to use.
+    #
+    # @return [void]
     def run(params={})
       # Extract params
       config_name = params.has_key?(:config_name) ? params[:config_name].to_sym : :default
       dry_run     = params.has_key?(:dry_run)     ? params[:dry_run]            : false
 