class YardGhurt::GHPSyncTask

Sync YARDoc to a local GitHub Pages repo (uses rsync by default).

@example What I Use

YardGhurt::GHPSyncTask.new() do |task|
  task.ghp_dir = '../esotericpig.github.io/docs/yard_ghurt/yardoc'
  task.sync_args << '--delete-after'
end

@example Using All Options

# Execute: rake ghp_doc[false,'Ruby']
YardGhurt::GHPSyncTask.new(:ghp_doc) do |task|
  task.arg_names   << :name                      # Custom args
  task.deps        << :yard                      # Custom dependencies
  task.description  = 'Rsync my_doc/ to my page'
  task.doc_dir      = 'my_doc'                   # YARDoc directory of generated files
  task.ghp_dir      = '../dest_dir/my_page'
  task.strict       = true                       # Fail if doc_dir doesn't exist
  task.sync_args   << '--delete-after'
  task.sync_cmd     = '/usr/bin/rsync'

  task.before = Proc.new() {|task,args| puts "Hi, #{args.name}!"}
  task.after  = Proc.new() {|task,args| puts "Goodbye, #{args.name}!"}
end

@author Jonathan Bradley Whited @since 1.1.0

Attributes

after[RW]

@return [Proc,nil] the Proc ( +respond_to?(:call)+ ) to call at the end of this task or nil;

default: +nil+
arg_names[RW]

@note :deploy will be added no matter what (cannot be deleted)

@return [Array<Symbol>,Symbol] the custom arg(s) for this task; default: [:deploy]

before[RW]

@return [Proc,nil] the Proc ( +respond_to?(:call)+ ) to call at the beginning of this task or nil;

default: +nil+
deps[RW]

@example

task.deps = :yard
# or...
task.deps = [:yard,:yard_gfm_fix]

@return [Array<Symbol>,Symbol] the custom dependencies for this task; default: []

description[RW]

@return [String] the description of this task (customizable)

doc_dir[RW]

@return [String] the source directory of generated YARDoc files; default: doc

ghp_dir[RW]

@note You must set this, else an error is thrown.

@return [String] the destination directory to sync {doc_dir} to

name[RW]

@return [String] the name of this task (customizable); default: yard_ghp_sync

strict[RW]

If you want to use a non-local {doc_dir} (a remote host), set this to false.

@return [true,false] whether to throw an error if {doc_dir} does not exist; default: true

strict?[RW]

If you want to use a non-local {doc_dir} (a remote host), set this to false.

@return [true,false] whether to throw an error if {doc_dir} does not exist; default: true

sync_args[RW]

@note You should pass in multi-args separately: +['–exclude','*~']+ @note You should not single/double quote the args; +['“*~”']+ is unnecessary.

@return [Array<String>] the args to pass to the {sync_cmd}; default: +['-ahv','–progress']+

sync_cmd[RW]

@return [String] the sync command to use on the command line; default: rsync

Public Class Methods

new(name=:yard_ghp_sync) { |self| ... } click to toggle source

@param name [Symbol] the name of this task to use on the command line with rake

Calls superclass method
# File lib/yard_ghurt/ghp_sync_task.rb, line 100
def initialize(name=:yard_ghp_sync)
  super()

  @after = nil
  @arg_names = []
  @before = nil
  @deps = []
  @description = 'Sync YARDoc to GitHub Pages repo'
  @doc_dir = 'doc'
  @ghp_dir = nil
  @name = name
  @strict = true
  @sync_args = ['-ahv','--progress']
  @sync_cmd = 'rsync'

  yield self if block_given?
  define
end

Public Instance Methods

build_sh_cmd(deploy) click to toggle source

Build the sync command to use on the command line.

@param deploy [true,false] whether to actually deploy (true) or to run a dry-run (false)

@return [Array<String>] the sync command and its args

# File lib/yard_ghurt/ghp_sync_task.rb, line 160
def build_sh_cmd(deploy)
  sh_cmd = [@sync_cmd]

  sh_cmd << '--dry-run' unless deploy
  sh_cmd.push(*@sync_args)

  # File.join() to add a trailing '/' if not present
  sh_cmd << File.join(@doc_dir,'')
  sh_cmd << File.join(@ghp_dir,'')

  return sh_cmd
end
define() click to toggle source

Define the Rake task and description using the instance variables.

# File lib/yard_ghurt/ghp_sync_task.rb, line 120
def define
  @arg_names = *@arg_names
  @arg_names.unshift(:deploy) unless @arg_names.include?(:deploy)

  desc @description
  task @name,@arg_names => Array(@deps) do |task,args|
    deploy = Util.to_bool(args.deploy)

    @before.call(self,args) if @before.respond_to?(:call)

    # Without these checks, sh raises some pretty cryptic errors.
    if @strict
      # If you want to use a non-local dir, set strict to false.
      if !File.exist?(@doc_dir)
        raise ArgumentError,%Q(#{self.class}.doc_dir [#{@doc_dir}] does not exist; execute "rake yard"?)
      end
    end
    # Do not check if ghp_dir exists because rsync may create it.
    if @ghp_dir.nil? || @ghp_dir.to_s.strip.empty?
      raise ArgumentError,"#{self.class}.ghp_dir must be set"
    end

    sh(*build_sh_cmd(deploy))

    if !deploy
      puts
      puts %Q(Execute "rake #{@name}[true]" for actually deploying (not a dry-run))
    end

    @after.call(self,args) if @after.respond_to?(:call)
  end

  return self
end