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

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



78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
 
# File 'lib/yard_ghurt/ghp_sync_task.rb', line 78

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



28
29
30
 
# File 'lib/yard_ghurt/ghp_sync_task.rb', line 28

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



33
34
35
 
# File 'lib/yard_ghurt/ghp_sync_task.rb', line 33

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



37
38
39
 
# File 'lib/yard_ghurt/ghp_sync_task.rb', line 37

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



45
46
47
 
# File 'lib/yard_ghurt/ghp_sync_task.rb', line 45

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



48
49
50
 
# File 'lib/yard_ghurt/ghp_sync_task.rb', line 48

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



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

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



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

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



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

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



64
65
66
 
# File 'lib/yard_ghurt/ghp_sync_task.rb', line 64

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



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

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



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

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



137
138
139
140
141
142
143
144
145
146
147
148
 
# File 'lib/yard_ghurt/ghp_sync_task.rb', line 137

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



98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
 
# File 'lib/yard_ghurt/ghp_sync_task.rb', line 98

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 the below checks, sh() raises some pretty cryptic errors.

    # If you want to use a non-local dir, set strict to false.
    if @strict && !File.exist?(@doc_dir)
      raise ArgumentError,%(#{self.class}.doc_dir [#{@doc_dir}] does not exist; execute "rake yard"?)
    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 %(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