class RDoc::Task

RDoc::Task 创建以下 rake 任务来生成和清理 RDoc 输出

rdoc: 此 RDoc 任务的主要任务。
clobber_rdoc: 删除所有 rdoc 文件。此目标会自动添加到主 clobber 目标。
rerdoc: 从头开始重建 rdoc 文件，即使它们不是过时的。
rdoc:coverage: 打印所有 rdoc 文件的 RDoc 覆盖率报告。

简单示例

require 'rdoc/task'

RDoc::Task.new do |rdoc|
  rdoc.main = "README.rdoc"
  rdoc.rdoc_files.include("README.rdoc", "lib/**/*.rb")
end

传递给块的 rdoc 对象是一个 RDoc::Task 对象。有关可用的自定义选项，请参见 RDoc::Task 类的属性列表。

指定不同的任务名称¶ ↑

您可能希望为该任务指定不同的名称，例如，如果要生成两组文档。例如，如果您想拥有一个包含私有方法的开发文档集

require 'rdoc/task'

RDoc::Task.new :rdoc_dev do |rdoc|
  rdoc.main = "README.rdoc"
  rdoc.rdoc_files.include("README.rdoc", "lib/**/*.rb")
  rdoc.options << "--all"
end

那么这些任务的名称将为：rdoc_dev、:clobber_rdoc_dev 和 :rerdoc_dev。

如果您希望拥有完全不同的任务名称，请将 Hash 作为第一个参数传递。使用 :rdoc、:clobber_rdoc 和 :rerdoc 选项，您可以根据自己的喜好自定义任务名称。

例如

require 'rdoc/task'

RDoc::Task.new(:rdoc => "rdoc", :clobber_rdoc => "rdoc:clean",
               :rerdoc => "rdoc:force")

这将创建任务 :rdoc、:rdoc:clean、:rdoc:force 和 :rdoc:coverage。

属性

external[RW]

是否将 rdoc 进程作为外部 shell 运行（默认为 false）

generator[RW]

rdoc 使用的格式生成器（--format）的名称。（默认为 rdoc 的默认值）

main[RW]

用作 RDoc 的主要顶层文件的文件名。（默认为无）

markup[RW]

标记格式；以下之一：rdoc（默认）、markdown、rd、tomdoc。请参阅标记格式。

name[RW]

主要顶层任务的名称。（默认为：rdoc）

options[RW]

要传递给 rdoc 的其他选项列表。（默认为 []）

rdoc_dir[RW]

接收 html 输出文件的目录名称。（默认为 “html”）

rdoc_files[RW]

要包含在 rdoc 生成中的文件列表。（默认为 []）

template[RW]

rdoc 使用的模板名称。（默认为 rdoc 的默认值）

title[RW]

RDoc 文档的标题。（默认为 rdoc 的默认值）

公共类方法

new(name = :rdoc) { |self| ... } 单击以切换源

使用给定的名称创建一个 RDoc 任务。有关文档，请参阅 RDoc::Task 类概述。

# File rdoc/task.rb, line 157
def initialize name = :rdoc # :yield: self
  defaults

  check_names name

  @name = name

  yield self if block_given?

  define
end

公共实例方法

before_running_rdoc(&block) 单击以切换源

此方法传递的块将在运行 RDoc 生成器之前调用。允许在块内修改 RDoc::Task 属性。

# File rdoc/task.rb, line 287
def before_running_rdoc(&block)
  @before_running_rdoc = block
end

check_names(names) 单击以切换源

确保 names 仅包含 :rdoc、:clobber_rdoc 和 :rerdoc 的名称。如果给出了其他名称，则会引发 ArgumentError。

# File rdoc/task.rb, line 173
def check_names names
  return unless Hash === names

  invalid_options =
    names.keys.map { |k| k.to_sym } - [:rdoc, :clobber_rdoc, :rerdoc]

  unless invalid_options.empty? then
    raise ArgumentError, "invalid options: #{invalid_options.join ', '}"
  end
end

clobber_task_description() 单击以切换源

clobber rdoc 任务或其重命名等效项的 Task 描述

# File rdoc/task.rb, line 187
def clobber_task_description
  "Remove RDoc HTML files"
end

coverage_task_description() 单击以切换源

覆盖率任务或其重命名描述的 Task 描述

# File rdoc/task.rb, line 308
def coverage_task_description
  "Print RDoc coverage report"
end

defaults() 单击以切换源

设置默认任务值

# File rdoc/task.rb, line 194
def defaults
  @name = :rdoc
  @rdoc_files = Rake::FileList.new
  @rdoc_dir = 'html'
  @main = nil
  @title = nil
  @template = nil
  @generator = nil
  @options = []
end

define() 单击以切换源

创建此任务库定义的任务。

# File rdoc/task.rb, line 223
def define
  desc rdoc_task_description
  task rdoc_task_name

  desc rerdoc_task_description
  task rerdoc_task_name => [clobber_task_name, rdoc_task_name]

  desc clobber_task_description
  task clobber_task_name do
    rm_r @rdoc_dir rescue nil
  end

  task :clobber => [clobber_task_name]

  directory @rdoc_dir

  rdoc_target_deps = [
    @rdoc_files,
    Rake.application.rakefile
  ].flatten.compact

  task rdoc_task_name => [rdoc_target]
  file rdoc_target => rdoc_target_deps do
    @before_running_rdoc.call if @before_running_rdoc
    args = option_list + @rdoc_files

    $stderr.puts "rdoc #{args.join ' '}" if Rake.application.options.trace
    RDoc::RDoc.new.document args
  end

  namespace rdoc_task_name do
    desc coverage_task_description
    task coverage_task_name do
      @before_running_rdoc.call if @before_running_rdoc
      opts = option_list << "-C"
      args = opts + @rdoc_files

      $stderr.puts "rdoc #{args.join ' '}" if Rake.application.options.trace
      RDoc::RDoc.new.document args
    end
  end

  self
end

option_list() 单击以切换源

将提供给 RDoc 的选项列表

# File rdoc/task.rb, line 271
def option_list
  result = @options.dup
  result << "-o"       << @rdoc_dir
  result << "--main"   << main      if main
  result << "--markup" << markup    if markup
  result << "--title"  << title     if title
  result << "-T"       << template  if template
  result << '-f'       << generator if generator
  result
end

rdoc_task_description() 单击以切换源

rdoc 任务或其重命名等效项的 Task 描述

# File rdoc/task.rb, line 294
def rdoc_task_description
  'Build RDoc HTML files'
end

rerdoc_task_description() 单击以切换源

rerdoc 任务或其重命名描述的 Task 描述

# File rdoc/task.rb, line 301
def rerdoc_task_description
  "Rebuild RDoc HTML files"
end

私有实例方法

clobber_task_name() 单击以切换源

# File rdoc/task.rb, line 325
def clobber_task_name
  case name
  when Hash then (name[:clobber_rdoc] || "clobber_rdoc").to_s
  else           "clobber_#{name}"
  end
end

coverage_task_name() 单击以切换源

# File rdoc/task.rb, line 339
def coverage_task_name
  "coverage"
end

rdoc_target() 单击以切换源

# File rdoc/task.rb, line 314
def rdoc_target
  "#{rdoc_dir}/created.rid"
end

rdoc_task_name() 单击以切换源

# File rdoc/task.rb, line 318
def rdoc_task_name
  case name
  when Hash then (name[:rdoc] || "rdoc").to_s
  else           name.to_s
  end
end

rerdoc_task_name() 单击以切换源

# File rdoc/task.rb, line 332
def rerdoc_task_name
  case name
  when Hash then (name[:rerdoc] || "rerdoc").to_s
  else           "re#{name}"
  end
end