Class: Inventory::Rake::Tasks::YARD

Inherits:
Object
  • Object
show all
Includes:
Rake::DSL
Defined in:
lib/inventory-rake-tasks-yard-1.0.rb,
lib/inventory-rake-tasks-yard-1.0/version.rb

Overview

Defines a task that invokes YARD to process embedded documentation.

Constant Summary collapse

Version = 
Inventory.new(1, 4, 1){
  authors{
    author 'Nikolai Weibull', '[email protected]'
  }

  homepage 'http://disu.se/software/inventory-rake-tasks-yard'

  licenses{
    license 'LGPLv3+',
            'GNU Lesser General Public License, version 3 or later',
            'http://www.gnu.org/licenses/'
  }

  def dependencies
    super + Inventory::Dependencies.new{
      development 'lookout', 3, 0, 0
      development 'lookout-rake', 3, 1, 0
      development 'yard-heuristics', 1, 1, 0
      runtime 'inventory-rake', 1, 6, 0
      runtime 'rake', 10, 0, 0, :feature => 'rake'
      optional 'yard', 0, 8, 0
    }
  end

  def requires
    %w[shellwords]
  end

  def additional_libs
    super + %w[inventory/rake/tasks/yard-1.0.rb]
  end

  def unit_tests
    super - %w[inventory/rake/tasks/yard-1.0.rb]
  end
}

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = {}) {|?| ... } ⇒ YARD

Sets up a YARD task NAME, passing OPTIONS, on the files listed in INVENTORY or FILES, with GLOBALS set, optionally yields the task object for further customization, then #defines NAME.

The default for OPTIONS is:

--no-private --protected --private --query \
  "(!object.docstring.blank?&&object.docstring.line)||object.root?" \
--markup markdown --no-stats

This’ll make YARD output documentation for all public, protected, and private objects not markes as @private that have documentation that hasn’t been automatically generated or is the top-level namespace using Markdown as the markup format and not outputting any statistics at the end of execution.

Parameters:

  • options (Hash) (defaults to: {})

Options Hash (options):

  • :name (Symbol) — default: :html —

    The name of the task to define

  • :options (Array<String, Array<String>>) — default: … —

    The options to pass to YARD; will be passed to Shellwords.shelljoin

  • :inventory (Inventory) — default: Inventory::Rake::Tasks.inventory —

    The inventory to use for FILES default

  • :files (Array<String>) — default: FileList[ENV['FILES']] or inventory.lib_files —

    The files to process

  • :globals (Hash) — default: {} —

    The globals to pass to YARD

Yields:

  • (?)

Yield Parameters:

  • task (self) 


50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
 
# File 'lib/inventory-rake-tasks-yard-1.0.rb', line 50

def initialize(options = {})
  self.name = options.fetch(:name, :html)
  self.options = options.fetch(:options,
                               ['--no-private',
                                '--protected',
                                '--private',
                                ['--query', %w{'(!object.docstring.blank?&&object.docstring.line)||object.root?'}],
                                ['--markup', 'markdown'],
                                '--no-stats'])
  self.inventory = options.fetch(:inventory, Inventory::Rake::Tasks.inventory)
  self.files = options.fetch(:files){
    ENV.include?('FILES') ?
      FileList[ENV['FILES']] :
      (n = 0; inventory.lib_files.sort_by{ |e| [e.count('/'), n += 1] })
  }
  self.globals = options.fetch(:globals, {})
  yield self if block_given?
  define
end

Instance Attribute Details

#files ⇒ Array<String>

Returns The files to process: VALUE.

Parameters:

  • value (Array<String>)

Returns:

  • (Array<String>) —

    The files to process: VALUE



124
125
126
 
# File 'lib/inventory-rake-tasks-yard-1.0.rb', line 124

def files
  @files
end

#globals ⇒ Hash

Returns The globals to pass to YARD: VALUE.

Parameters:

  • value (Hash)

Returns:

  • (Hash) —

    The globals to pass to YARD: VALUE



128
129
130
 
# File 'lib/inventory-rake-tasks-yard-1.0.rb', line 128

def globals
  @globals
end

#inventory ⇒ Inventory

Returns The inventory to use: VALUE.

Parameters:

Returns:

  • (Inventory) —

    The inventory to use: VALUE



120
121
122
 
# File 'lib/inventory-rake-tasks-yard-1.0.rb', line 120

def inventory
  @inventory
end

#name ⇒ Symbol

Returns The name to use for the task: VALUE.

Parameters:

  • value (Symbol)

Returns:

  • (Symbol) —

    The name to use for the task: VALUE



112
113
114
 
# File 'lib/inventory-rake-tasks-yard-1.0.rb', line 112

def name
  @name
end

#options ⇒ Array<String, Array<String>>

Returns The options to pass to YARD: VALUE.

Parameters:

  • value (Array<String, Array<String>>)

Returns:

  • (Array<String, Array<String>>) —

    The options to pass to YARD: VALUE



116
117
118
 
# File 'lib/inventory-rake-tasks-yard-1.0.rb', line 116

def options
  @options
end

Instance Method Details

#define ⇒ Object

Defines the following tasks (html is actually whatever #name has been set to):

.yardopts (file)
Create .yardopts file based on #options; depends on the file defining this task and Rakefile.
html
Generate documentation in HTML format for all #files, passing #globals to YARD; depends on .yardopts file.


82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
 
# File 'lib/inventory-rake-tasks-yard-1.0.rb', line 82

def define
  desc 'Create .yardopts file'
  file '.yardopts' => [__FILE__, 'Rakefile'] do |t|
    tmp = '%s.tmp' % t.name
    rm([t.name, tmp], :force => true)
    rake_output_message 'echo %s > %s' % [options.join(' '), tmp] if verbose
    File.open(tmp, 'wb') do |f|
      f.write options.join(' ')
    end
    chmod File.stat(tmp).mode & ~0222, tmp
    mv tmp, t.name
  end

  desc name == :html ?
    'Generate documentation in HTML format' :
    'Generate documentation for %s in HTML format' % name
  task name => '.yardopts' do
    require 'yard'
    yardoc = YARD::CLI::Yardoc.new
    yardoc.parse_arguments(*arguments)
    globals.each do |key, value|
      yardoc.options.globals.send '%s=' % key, value
    end
    rake_output_message 'yard doc %s' % Shellwords.shelljoin(arguments(yardopts(yardoc))) if verbose
    yardoc.run(nil)
  end
end