Class: YardGhurt::GHPSyncTask

Inherits:
Rake::TaskLib
  • Object
show all
Defined in:
lib/yard_ghurt/ghp_sync_task.rb

Overview

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

Examples:

What I Use

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

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

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(name = :yard_ghp_sync) {|_self| ... } ⇒ GHPSyncTask

Returns a new instance of GHPSyncTask.

Parameters:

  • name (Symbol) (defaults to: :yard_ghp_sync) —

    the name of this task to use on the command line with rake

Yields:

  • (_self)

Yield Parameters:

Since:

  • 1.1.0



100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
 
# 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

Instance Attribute Details

#after ⇒ Proc?

Returns the Proc ( respond_to?(:call) ) to call at the end of this task or nil; default: nil.

Returns:

  • (Proc, nil) —

    the Proc ( respond_to?(:call) ) to call at the end of this task or nil; default: nil

Since:

  • 1.1.0



50
51
52
 
# File 'lib/yard_ghurt/ghp_sync_task.rb', line 50

def after
  @after
end

#arg_names ⇒ Array<Symbol>, Symbol

Note:

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

Returns the custom arg(s) for this task; default: [:deploy].

Returns:

  • (Array<Symbol>, Symbol) —

    the custom arg(s) for this task; default: [:deploy]

Since:

  • 1.1.0



55
56
57
 
# File 'lib/yard_ghurt/ghp_sync_task.rb', line 55

def arg_names
  @arg_names
end

#before ⇒ Proc?

Returns the Proc ( respond_to?(:call) ) to call at the beginning of this task or nil; default: nil.

Returns:

  • (Proc, nil) —

    the Proc ( respond_to?(:call) ) to call at the beginning of this task or nil; default: nil

Since:

  • 1.1.0



59
60
61
 
# File 'lib/yard_ghurt/ghp_sync_task.rb', line 59

def before
  @before
end

#deps ⇒ Array<Symbol>, Symbol

Returns the custom dependencies for this task; default: [].

Examples:

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

Returns:

  • (Array<Symbol>, Symbol) —

    the custom dependencies for this task; default: []

Since:

  • 1.1.0



67
68
69
 
# File 'lib/yard_ghurt/ghp_sync_task.rb', line 67

def deps
  @deps
end

#description ⇒ String

Returns the description of this task (customizable).

Returns:

  • (String) —

    the description of this task (customizable)

Since:

  • 1.1.0



70
71
72
 
# File 'lib/yard_ghurt/ghp_sync_task.rb', line 70

def description
  @description
end

#doc_dir ⇒ String

Returns the source directory of generated YARDoc files; default: doc.

Returns:

  • (String) —

    the source directory of generated YARDoc files; default: doc

Since:

  • 1.1.0



73
74
75
 
# File 'lib/yard_ghurt/ghp_sync_task.rb', line 73

def doc_dir
  @doc_dir
end

#ghp_dir ⇒ String

Note:

You must set this, else an error is thrown.

Returns the destination directory to sync #doc_dir to.

Returns:

  • (String) —

    the destination directory to sync #doc_dir to

Since:

  • 1.1.0



78
79
80
 
# File 'lib/yard_ghurt/ghp_sync_task.rb', line 78

def ghp_dir
  @ghp_dir
end

#name ⇒ String

Returns the name of this task (customizable); default: yard_ghp_sync.

Returns:

  • (String) —

    the name of this task (customizable); default: yard_ghp_sync

Since:

  • 1.1.0



81
82
83
 
# File 'lib/yard_ghurt/ghp_sync_task.rb', line 81

def name
  @name
end

#strict ⇒ true, false Also known as: strict?

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

Returns:

  • (true, false) —

    whether to throw an error if #doc_dir does not exist; default: true

Since:

  • 1.1.0



86
87
88
 
# File 'lib/yard_ghurt/ghp_sync_task.rb', line 86

def strict
  @strict
end

#sync_args ⇒ Array<String>

Note:

You should pass in multi-args separately: ['–exclude','*~']

Note:

You should not single/double quote the args; ['“*~”'] is unnecessary.

Returns the args to pass to the #sync_cmd; default: ['-ahv','–progress'].

Returns:

  • (Array<String>) —

    the args to pass to the #sync_cmd; default: ['-ahv','–progress']

Since:

  • 1.1.0



92
93
94
 
# File 'lib/yard_ghurt/ghp_sync_task.rb', line 92

def sync_args
  @sync_args
end

#sync_cmd ⇒ String

Returns the sync command to use on the command line; default: rsync.

Returns:

  • (String) —

    the sync command to use on the command line; default: rsync

Since:

  • 1.1.0



95
96
97
 
# File 'lib/yard_ghurt/ghp_sync_task.rb', line 95

def sync_cmd
  @sync_cmd
end

Instance Method Details

#build_sh_cmd(deploy) ⇒ Array<String>

Build the sync command to use on the command line.

Parameters:

  • deploy (true, false) —

    whether to actually deploy (true) or to run a dry-run (false)

Returns:

  • (Array<String>) —

    the sync command and its args

Since:

  • 1.1.0



160
161
162
163
164
165
166
167
168
169
170
171
 
# 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 ⇒ Object

Define the Rake task and description using the instance variables.

Since:

  • 1.1.0



120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
 
# 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