summaryrefslogtreecommitdiff
path: root/lib/rake/rdoctask.rb
blob: 33c8675b9e200ae31766d77ed6225912af73d406 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
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
109
110
111
112
113
114
115
116
117
118
119
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
require 'rake'
require 'rake/tasklib'

module Rake

  # Create a documentation task that will generate the RDoc files for
  # a project.
  #
  # The RDocTask will create the following targets:
  #
  # [<b><em>rdoc</em></b>]
  #   Main task for this RDOC task.
  #
  # [<b>:clobber_<em>rdoc</em></b>]
  #   Delete all the rdoc files.  This target is automatically
  #   added to the main clobber target.
  #
  # [<b>:re<em>rdoc</em></b>]
  #   Rebuild the rdoc files from scratch, even if they are not out
  #   of date.
  #
  # Simple Example:
  #
  #   Rake::RDocTask.new do |rd|
  #     rd.main = "README.rdoc"
  #     rd.rdoc_files.include("README.rdoc", "lib/**/*.rb")
  #   end
  #
  # You may wish to give the task a different name, such as if you are
  # generating two sets of documentation.  For instance, if you want to have a
  # development set of documentation including private methods:
  #
  #   Rake::RDocTask.new(:rdoc_dev) do |rd|
  #     rd.main = "README.doc"
  #     rd.rdoc_files.include("README.rdoc", "lib/**/*.rb")
  #     rd.options << "--all"
  #   end
  #
  # The tasks would then be named :<em>rdoc_dev</em>, :clobber_<em>rdoc_dev</em>, and
  # :re<em>rdoc_dev</em>.
  #
  class RDocTask < TaskLib
    # Name of the main, top level task.  (default is :rdoc)
    attr_accessor :name

    # Name of directory to receive the html output files. (default is "html")
    attr_accessor :rdoc_dir

    # Title of RDoc documentation. (default is none)
    attr_accessor :title

    # Name of file to be used as the main, top level file of the
    # RDoc. (default is none)
    attr_accessor :main

    # Name of template to be used by rdoc. (defaults to rdoc's default)
    attr_accessor :template

    # List of files to be included in the rdoc generation. (default is [])
    attr_accessor :rdoc_files

    # List of options to be passed rdoc.  (default is [])
    attr_accessor :options

    # Run the rdoc process as an external shell (default is false)
    attr_accessor :external

    # Create an RDoc task named <em>rdoc</em>.  Default task name is +rdoc+.
    def initialize(name=:rdoc)  # :yield: self
      @name = name
      @rdoc_files = Rake::FileList.new
      @rdoc_dir = 'html'
      @main = nil
      @title = nil
      @template = nil
      @external = false
      @options = []
      yield self if block_given?
      define
    end

    # Create the tasks defined by this task lib.
    def define
      if name.to_s != "rdoc"
        desc "Build the RDOC HTML Files"
      end

      desc "Build the #{name} HTML Files"
      task name

      desc "Force a rebuild of the RDOC files"
      task "re#{name}" => ["clobber_#{name}", name]

      desc "Remove rdoc products"
      task "clobber_#{name}" do
        rm_r rdoc_dir rescue nil
      end

      task :clobber => ["clobber_#{name}"]

      directory @rdoc_dir
      task name => [rdoc_target]
      file rdoc_target => @rdoc_files + [Rake.application.rakefile] do
        rm_r @rdoc_dir rescue nil
        args = option_list + @rdoc_files
        if @external
          argstring = args.join(' ')
          sh %{ruby -Ivendor vender/rd #{argstring}}
        else
          require 'rdoc/rdoc'
          RDoc::RDoc.new.document(args)
        end
      end
      self
    end

    def option_list
      result = @options.dup
      result << "-o" << @rdoc_dir
      result << "--main" << quote(main) if main
      result << "--title" << quote(title) if title
      result << "-T" << quote(template) if template
      result
    end

    def quote(str)
      if @external
        "'#{str}'"
      else
        str
      end
    end

    def option_string
      option_list.join(' ')
    end

    private

    def rdoc_target
      "#{rdoc_dir}/index.html"
    end

  end
end