Class: Setup::Documentor Deprecated

Inherits:
Base
  • Object
show all
Defined in:
lib/setup/documentor.rb

Overview

Deprecated.

Setup.rb no longer generates ri documentation, ever.

As of v0.5.1 Setup.rb no longer support the document phase at all. The document phase would generate ri documentation for a project, adding in with the rest of ri documentation. After careful consideration, it has become clear that it is better for documentation to be left up to dedicated tools. For example, you could easily document your Ruby install site location yourself with

$ rdoc --ri-site /usr/local/lib/site_ruby

Using of course, whichever path is appropriate to your system.

This descision also allows setup.rb to be less Ruby-specific, and useful as a more general install tool.

Instance Attribute Summary

Attributes inherited from Base

#config, #force, #io, #project, #quiet, #trace, #trial

Instance Method Summary collapse

Methods inherited from Base

#bash, #force?, #force_remove_file, #initialize, #initialize_hooks, #quiet?, #remove_file, #rm_f, #rmdir, #rootdir, #ruby, #trace?, #trace_off, #trial?

Constructor Details

This class inherits a constructor from Setup::Base

Instance Method Details

#document ⇒ Object 



24
25
26
27
28
29
 
# File 'lib/setup/documentor.rb', line 24

def document
  return if config.no_doc

  exec_ri
  exec_yri
end

#exec_rdoc ⇒ Object

Deprecated.

This is not being used. It’s here in case we decide to add the feature back in the future.

Generate rdocs. Needs project name.



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
146
147
148
149
150
151
 
# File 'lib/setup/documentor.rb', line 99

def exec_rdoc
  main = Dir.glob("README{,.*}", File::FNM_CASEFOLD).first

  if File.exist?('.document')
    files = File.read('.document').split("\n")
    files.reject!{ |l| l =~ /^\s*[#]/ || l !~ /\S/ }
    files.collect!{ |f| f.strip }
  else
    files = []
    files << main  if main
    files << 'lib' if File.directory?('lib')
    files << 'ext' if File.directory?('ext')
  end

  checkfiles = (files + files.map{ |f| Dir[File.join(f,'*','**')] }).flatten.uniq
  if FileUtils.uptodate?('doc/rdoc', checkfiles)
    puts "RDocs look current."
    return
  end

  output    = 'doc/rdoc'
  title     = (PACKAGE.capitalize + " API").strip if PACKAGE
  template  = config.doctemplate || 'html'

  opt = []
  opt << "-U"
  opt << "-q" #if quiet?
  opt << "--op=#{output}"
  #opt << "--template=#{template}"
  opt << "--title=#{title}"
  opt << "--main=#{main}"     if main
  #opt << "--debug"
  opt << files

  opt = opt.flatten

  cmd = "rdoc " + opt.join(' ')

  if trial?
    puts cmd 
  else
    begin
      system(cmd)
      #require 'rdoc/rdoc'
      #::RDoc::RDoc.new.document(opt)
      puts "Ok rdoc." unless quiet?
    rescue Exception
      puts "Fail rdoc."
      puts "Command was: '#{cmd}'"
      puts "Proceeding with install anyway."
    end
  end
end

#exec_ri ⇒ Object

TODO:

Should we run rdoc programmatically instead of shelling out?

Generate ri documentation.



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
 
# File 'lib/setup/documentor.rb', line 35

def exec_ri
  case config.type #installdirs
  when 'home'
    output = "--ri"
  when 'site'
    output = "--ri-site"
  when 'std', 'ruby'
    output  = "--ri-site"
  else
    abort "bad config: should not be possible -- type=#{config.type}"
  end

  opt = []
  opt << "-U"
  opt << "-q" #if quiet?
  #opt << "-D" #if $DEBUG
  opt << output

  unless project.document
    files = []
    files << 'lib' if project.find('lib')
    files << 'ext' if project.find('ext')
  else
    files = []
    #files = File.read('.document').split("\n")
    #files.reject!{ |l| l =~ /^\s*[#]/ || l !~ /\S/ }
    #files.collect!{ |f| f.strip }
  end

  opt.concat(files)

  opt.flatten!

  cmd = "rdoc " + opt.join(' ')

  if trial?
    puts cmd
  else
    begin
      success = system(cmd)
      raise unless success
      #require 'rdoc/rdoc'
      #::RDoc::RDoc.new.document(opt)
      io.puts "Ok ri." #unless quiet?
    rescue Exception
      $stderr.puts "ri generation failed"
      $stderr.puts "command was: '#{cmd}'"
      #$stderr.puts "proceeding with install..."
    end
  end
end

#exec_yri ⇒ Object

Generate YARD Ruby Index documention.



90
91
92
 
# File 'lib/setup/documentor.rb', line 90

def exec_yri

end