class Setup::Documentor

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.

@deprecated Setup.rb no longer generates ri documentation, ever.

Public Instance Methods

document() click to toggle source
# File lib/setup/documentor.rb, line 24
def document
  return if config.no_doc

  exec_ri
  exec_yri
end
exec_rdoc() click to toggle source

Generate rdocs. Needs project name.

@deprecated This is not being used. It’s here in case we decide

to add the feature back in the future.
# 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() click to toggle source

Generate ri documentation.

@todo Should we run rdoc programmatically instead of shelling out?

# 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() click to toggle source

Generate YARD Ruby Index documention.

# File lib/setup/documentor.rb, line 90
def exec_yri

end