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](yardoc.org/) 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):

<dl>

<dt>.yardopts (file)</dt>
<dd>Create .yardopts file based on {#options}; depends on the file
defining this task and Rakefile.</dd>

<dt>html</dt>
<dd>Generate documentation in HTML format for all {#files}, passing
{#globals} to YARD; depends on .yardopts file.</dd>

</dl>



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