2008-01-08 04:07:31 -05:00
|
|
|
require 'rdoc'
|
|
|
|
|
2003-12-01 02:12:49 -05:00
|
|
|
require 'find'
|
2007-12-24 09:09:57 -05:00
|
|
|
require 'fileutils'
|
2012-11-27 03:54:03 -05:00
|
|
|
require 'pathname'
|
2006-09-17 10:46:13 -04:00
|
|
|
require 'time'
|
2003-12-01 02:12:49 -05:00
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
##
|
2012-11-26 23:28:14 -05:00
|
|
|
# This is the driver for generating RDoc output. It handles file parsing and
|
|
|
|
# generation of output.
|
2010-12-19 22:22:49 -05:00
|
|
|
#
|
2012-11-26 23:28:14 -05:00
|
|
|
# To use this class to generate RDoc output via the API, the recommended way
|
|
|
|
# is:
|
2010-12-19 22:22:49 -05:00
|
|
|
#
|
2012-11-26 23:28:14 -05:00
|
|
|
# rdoc = RDoc::RDoc.new
|
|
|
|
# options = rdoc.load_options # returns an RDoc::Options instance
|
|
|
|
# # set extra options
|
|
|
|
# rdoc.document options
|
2010-12-19 22:22:49 -05:00
|
|
|
#
|
2012-11-26 23:28:14 -05:00
|
|
|
# You can also generate output like the +rdoc+ executable:
|
2010-12-19 22:22:49 -05:00
|
|
|
#
|
2012-11-26 23:28:14 -05:00
|
|
|
# rdoc = RDoc::RDoc.new
|
|
|
|
# rdoc.document argv
|
2010-12-19 22:22:49 -05:00
|
|
|
#
|
2012-11-26 23:28:14 -05:00
|
|
|
# Where +argv+ is an array of strings, each corresponding to an argument you'd
|
|
|
|
# give rdoc on the command line. See <tt>rdoc --help<tt> for details.
|
2010-04-01 03:45:16 -04:00
|
|
|
|
|
|
|
class RDoc::RDoc
|
2003-12-01 02:12:49 -05:00
|
|
|
|
2012-11-26 23:28:14 -05:00
|
|
|
@current = nil
|
|
|
|
|
|
|
|
##
|
|
|
|
# This is the list of supported output generators
|
|
|
|
|
|
|
|
GENERATORS = {}
|
|
|
|
|
2008-01-07 01:56:46 -05:00
|
|
|
##
|
2010-04-01 03:45:16 -04:00
|
|
|
# File pattern to exclude
|
2008-01-07 01:56:46 -05:00
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
attr_accessor :exclude
|
2003-12-01 02:12:49 -05:00
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
##
|
|
|
|
# Generator instance used for creating output
|
2008-01-07 01:56:46 -05:00
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
attr_accessor :generator
|
2008-07-21 14:35:14 -04:00
|
|
|
|
2010-04-10 21:34:28 -04:00
|
|
|
##
|
|
|
|
# Hash of files and their last modified times.
|
|
|
|
|
|
|
|
attr_reader :last_modified
|
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
##
|
|
|
|
# RDoc options
|
2008-07-21 14:35:14 -04:00
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
attr_accessor :options
|
2008-01-07 01:56:46 -05:00
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
##
|
|
|
|
# Accessor for statistics. Available after each call to parse_files
|
2008-01-07 01:56:46 -05:00
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
attr_reader :stats
|
|
|
|
|
|
|
|
##
|
2012-11-26 23:28:14 -05:00
|
|
|
# The current documentation store
|
2010-04-01 03:45:16 -04:00
|
|
|
|
2012-11-26 23:28:14 -05:00
|
|
|
attr_reader :store
|
2010-04-01 03:45:16 -04:00
|
|
|
|
|
|
|
##
|
|
|
|
# Add +klass+ that can generate output after parsing
|
|
|
|
|
|
|
|
def self.add_generator(klass)
|
|
|
|
name = klass.name.sub(/^RDoc::Generator::/, '').downcase
|
|
|
|
GENERATORS[name] = klass
|
|
|
|
end
|
|
|
|
|
|
|
|
##
|
|
|
|
# Active RDoc::RDoc instance
|
|
|
|
|
|
|
|
def self.current
|
|
|
|
@current
|
|
|
|
end
|
|
|
|
|
|
|
|
##
|
|
|
|
# Sets the active RDoc::RDoc instance
|
|
|
|
|
2012-11-26 23:28:14 -05:00
|
|
|
def self.current= rdoc
|
2010-04-01 03:45:16 -04:00
|
|
|
@current = rdoc
|
|
|
|
end
|
|
|
|
|
2010-12-19 22:22:49 -05:00
|
|
|
##
|
|
|
|
# Creates a new RDoc::RDoc instance. Call #document to parse files and
|
|
|
|
# generate documentation.
|
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
def initialize
|
2010-04-10 21:34:28 -04:00
|
|
|
@current = nil
|
|
|
|
@exclude = nil
|
|
|
|
@generator = nil
|
|
|
|
@last_modified = {}
|
|
|
|
@old_siginfo = nil
|
|
|
|
@options = nil
|
|
|
|
@stats = nil
|
2012-11-26 23:28:14 -05:00
|
|
|
@store = nil
|
2010-04-01 03:45:16 -04:00
|
|
|
end
|
|
|
|
|
|
|
|
##
|
|
|
|
# Report an error message and exit
|
|
|
|
|
|
|
|
def error(msg)
|
|
|
|
raise RDoc::Error, msg
|
|
|
|
end
|
|
|
|
|
|
|
|
##
|
|
|
|
# Gathers a set of parseable files from the files and directories listed in
|
|
|
|
# +files+.
|
|
|
|
|
|
|
|
def gather_files files
|
|
|
|
files = ["."] if files.empty?
|
|
|
|
|
|
|
|
file_list = normalized_file_list files, true, @exclude
|
|
|
|
|
|
|
|
file_list = file_list.uniq
|
|
|
|
|
|
|
|
file_list = remove_unparseable file_list
|
2012-11-26 23:28:14 -05:00
|
|
|
|
|
|
|
file_list.sort
|
2010-04-01 03:45:16 -04:00
|
|
|
end
|
|
|
|
|
|
|
|
##
|
|
|
|
# Turns RDoc from stdin into HTML
|
|
|
|
|
|
|
|
def handle_pipe
|
2012-11-26 23:28:14 -05:00
|
|
|
@html = RDoc::Markup::ToHtml.new @options
|
|
|
|
|
|
|
|
parser = RDoc::Text::MARKUP_FORMAT[@options.markup]
|
2010-04-01 03:45:16 -04:00
|
|
|
|
2012-11-26 23:28:14 -05:00
|
|
|
document = parser.parse $stdin.read
|
|
|
|
|
|
|
|
out = @html.convert document
|
2010-04-01 03:45:16 -04:00
|
|
|
|
|
|
|
$stdout.write out
|
|
|
|
end
|
|
|
|
|
|
|
|
##
|
|
|
|
# Installs a siginfo handler that prints the current filename.
|
|
|
|
|
|
|
|
def install_siginfo_handler
|
|
|
|
return unless Signal.list.include? 'INFO'
|
|
|
|
|
|
|
|
@old_siginfo = trap 'INFO' do
|
|
|
|
puts @current if @current
|
2008-01-07 01:56:46 -05:00
|
|
|
end
|
2010-04-01 03:45:16 -04:00
|
|
|
end
|
2003-12-01 02:12:49 -05:00
|
|
|
|
2012-11-26 23:28:14 -05:00
|
|
|
##
|
|
|
|
# Loads options from .rdoc_options if the file exists, otherwise creates a
|
|
|
|
# new RDoc::Options instance.
|
|
|
|
|
|
|
|
def load_options
|
|
|
|
options_file = File.expand_path '.rdoc_options'
|
|
|
|
return RDoc::Options.new unless File.exist? options_file
|
|
|
|
|
|
|
|
RDoc.load_yaml
|
|
|
|
|
|
|
|
parse_error = if Object.const_defined? :Psych then
|
|
|
|
Psych::SyntaxError
|
|
|
|
else
|
|
|
|
ArgumentError
|
|
|
|
end
|
|
|
|
|
|
|
|
begin
|
|
|
|
options = YAML.load_file '.rdoc_options'
|
|
|
|
rescue *parse_error
|
|
|
|
end
|
|
|
|
|
|
|
|
raise RDoc::Error, "#{options_file} is not a valid rdoc options file" unless
|
|
|
|
RDoc::Options === options
|
|
|
|
|
|
|
|
options
|
|
|
|
end
|
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
##
|
|
|
|
# Create an output dir if it doesn't exist. If it does exist, but doesn't
|
|
|
|
# contain the flag file <tt>created.rid</tt> then we refuse to use it, as
|
|
|
|
# we may clobber some manually generated documentation
|
|
|
|
|
2010-04-10 21:34:28 -04:00
|
|
|
def setup_output_dir(dir, force)
|
|
|
|
flag_file = output_flag_file dir
|
2010-04-01 03:45:16 -04:00
|
|
|
|
2010-04-10 02:36:13 -04:00
|
|
|
last = {}
|
2010-04-03 05:15:13 -04:00
|
|
|
|
2010-12-19 22:22:49 -05:00
|
|
|
if @options.dry_run then
|
|
|
|
# do nothing
|
|
|
|
elsif File.exist? dir then
|
2010-04-10 21:34:28 -04:00
|
|
|
error "#{dir} exists and is not a directory" unless File.directory? dir
|
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
begin
|
2010-04-10 02:36:13 -04:00
|
|
|
open flag_file do |io|
|
2010-04-10 21:34:28 -04:00
|
|
|
unless force then
|
2010-04-10 18:41:36 -04:00
|
|
|
Time.parse io.gets
|
2010-04-10 21:34:28 -04:00
|
|
|
|
2010-04-10 02:36:13 -04:00
|
|
|
io.each do |line|
|
2010-04-10 21:34:28 -04:00
|
|
|
file, time = line.split "\t", 2
|
2010-04-03 05:15:13 -04:00
|
|
|
time = Time.parse(time) rescue next
|
|
|
|
last[file] = time
|
|
|
|
end
|
|
|
|
end
|
|
|
|
end
|
2010-04-10 21:34:28 -04:00
|
|
|
rescue SystemCallError, TypeError
|
|
|
|
error <<-ERROR
|
|
|
|
|
|
|
|
Directory #{dir} already exists, but it looks like it isn't an RDoc directory.
|
|
|
|
|
|
|
|
Because RDoc doesn't want to risk destroying any of your existing files,
|
|
|
|
you'll need to specify a different output directory name (using the --op <dir>
|
|
|
|
option)
|
|
|
|
|
|
|
|
ERROR
|
2010-12-19 22:22:49 -05:00
|
|
|
end unless @options.force_output
|
2010-04-01 03:45:16 -04:00
|
|
|
else
|
2010-04-10 21:34:28 -04:00
|
|
|
FileUtils.mkdir_p dir
|
2013-09-18 19:33:36 -04:00
|
|
|
FileUtils.touch flag_file
|
2008-02-09 22:59:08 -05:00
|
|
|
end
|
2003-12-01 02:12:49 -05:00
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
last
|
|
|
|
end
|
|
|
|
|
2012-11-26 23:28:14 -05:00
|
|
|
##
|
|
|
|
# Sets the current documentation tree to +store+ and sets the store's rdoc
|
|
|
|
# driver to this instance.
|
|
|
|
|
|
|
|
def store= store
|
|
|
|
@store = store
|
|
|
|
@store.rdoc = self
|
|
|
|
end
|
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
##
|
|
|
|
# Update the flag file in an output directory.
|
|
|
|
|
2010-04-03 05:15:13 -04:00
|
|
|
def update_output_dir(op_dir, time, last = {})
|
2011-02-01 19:32:30 -05:00
|
|
|
return if @options.dry_run or not @options.update_output_dir
|
2010-12-19 22:22:49 -05:00
|
|
|
|
2010-04-10 21:34:28 -04:00
|
|
|
open output_flag_file(op_dir), "w" do |f|
|
2010-04-03 05:15:13 -04:00
|
|
|
f.puts time.rfc2822
|
|
|
|
last.each do |n, t|
|
|
|
|
f.puts "#{n}\t#{t.rfc2822}"
|
|
|
|
end
|
|
|
|
end
|
2010-04-01 03:45:16 -04:00
|
|
|
end
|
|
|
|
|
|
|
|
##
|
|
|
|
# Return the path name of the flag file in an output directory.
|
|
|
|
|
|
|
|
def output_flag_file(op_dir)
|
|
|
|
File.join op_dir, "created.rid"
|
|
|
|
end
|
|
|
|
|
|
|
|
##
|
|
|
|
# The .document file contains a list of file and directory name patterns,
|
|
|
|
# representing candidates for documentation. It may also contain comments
|
|
|
|
# (starting with '#')
|
|
|
|
|
|
|
|
def parse_dot_doc_file in_dir, filename
|
|
|
|
# read and strip comments
|
|
|
|
patterns = File.read(filename).gsub(/#.*/, '')
|
2008-01-07 01:56:46 -05:00
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
result = []
|
|
|
|
|
|
|
|
patterns.split.each do |patt|
|
|
|
|
candidates = Dir.glob(File.join(in_dir, patt))
|
|
|
|
result.concat normalized_file_list(candidates)
|
2003-12-01 02:12:49 -05:00
|
|
|
end
|
2008-01-07 01:56:46 -05:00
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
result
|
|
|
|
end
|
|
|
|
|
|
|
|
##
|
|
|
|
# Given a list of files and directories, create a list of all the Ruby
|
|
|
|
# files they contain.
|
|
|
|
#
|
|
|
|
# If +force_doc+ is true we always add the given files, if false, only
|
|
|
|
# add files that we guarantee we can parse. It is true when looking at
|
|
|
|
# files given on the command line, false when recursing through
|
|
|
|
# subdirectories.
|
|
|
|
#
|
|
|
|
# The effect of this is that if you want a file with a non-standard
|
|
|
|
# extension parsed, you must name it explicitly.
|
|
|
|
|
|
|
|
def normalized_file_list(relative_files, force_doc = false,
|
|
|
|
exclude_pattern = nil)
|
|
|
|
file_list = []
|
|
|
|
|
|
|
|
relative_files.each do |rel_file_name|
|
2013-09-18 19:33:36 -04:00
|
|
|
next if rel_file_name.end_with? 'created.rid'
|
2010-04-01 03:45:16 -04:00
|
|
|
next if exclude_pattern && exclude_pattern =~ rel_file_name
|
|
|
|
stat = File.stat rel_file_name rescue next
|
2008-01-07 01:56:46 -05:00
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
case type = stat.ftype
|
2010-04-10 02:36:13 -04:00
|
|
|
when "file" then
|
2010-04-10 21:34:28 -04:00
|
|
|
next if last_modified = @last_modified[rel_file_name] and
|
|
|
|
stat.mtime.to_i <= last_modified.to_i
|
2010-04-01 03:45:16 -04:00
|
|
|
|
|
|
|
if force_doc or RDoc::Parser.can_parse(rel_file_name) then
|
|
|
|
file_list << rel_file_name.sub(/^\.\//, '')
|
2010-04-10 21:34:28 -04:00
|
|
|
@last_modified[rel_file_name] = stat.mtime
|
2003-12-01 02:12:49 -05:00
|
|
|
end
|
2010-04-10 02:36:13 -04:00
|
|
|
when "directory" then
|
2010-04-01 03:45:16 -04:00
|
|
|
next if rel_file_name == "CVS" || rel_file_name == ".svn"
|
|
|
|
|
2014-09-04 21:41:25 -04:00
|
|
|
created_rid = File.join rel_file_name, "created.rid"
|
|
|
|
next if File.file? created_rid
|
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
dot_doc = File.join rel_file_name, RDoc::DOT_DOC_FILENAME
|
|
|
|
|
2010-04-10 02:36:13 -04:00
|
|
|
if File.file? dot_doc then
|
2010-04-01 03:45:16 -04:00
|
|
|
file_list << parse_dot_doc_file(rel_file_name, dot_doc)
|
2006-09-17 10:46:13 -04:00
|
|
|
else
|
2010-04-01 03:45:16 -04:00
|
|
|
file_list << list_files_in_directory(rel_file_name)
|
2003-12-01 02:12:49 -05:00
|
|
|
end
|
|
|
|
else
|
2012-11-26 23:28:14 -05:00
|
|
|
warn "rdoc can't parse the #{type} #{rel_file_name}"
|
2003-12-01 02:12:49 -05:00
|
|
|
end
|
2006-09-17 10:46:13 -04:00
|
|
|
end
|
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
file_list.flatten
|
|
|
|
end
|
2008-01-07 01:56:46 -05:00
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
##
|
|
|
|
# Return a list of the files to be processed in a directory. We know that
|
|
|
|
# this directory doesn't have a .document file, so we're looking for real
|
|
|
|
# files. However we may well contain subdirectories which must be tested
|
|
|
|
# for .document files.
|
2006-09-17 10:46:13 -04:00
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
def list_files_in_directory dir
|
|
|
|
files = Dir.glob File.join(dir, "*")
|
2008-01-07 01:56:46 -05:00
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
normalized_file_list files, false, @options.exclude
|
|
|
|
end
|
2003-12-01 02:12:49 -05:00
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
##
|
|
|
|
# Parses +filename+ and returns an RDoc::TopLevel
|
2008-01-07 01:56:46 -05:00
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
def parse_file filename
|
2014-09-04 21:41:25 -04:00
|
|
|
if Object.const_defined? :Encoding then
|
2011-06-16 00:59:24 -04:00
|
|
|
encoding = @options.encoding
|
|
|
|
filename = filename.encode encoding
|
|
|
|
end
|
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
@stats.add_file filename
|
2010-12-19 22:22:49 -05:00
|
|
|
|
2013-09-18 19:33:36 -04:00
|
|
|
return if RDoc::Parser.binary? filename
|
|
|
|
|
2010-12-19 22:22:49 -05:00
|
|
|
content = RDoc::Encoding.read_file filename, encoding
|
2004-01-02 01:01:12 -05:00
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
return unless content
|
2004-01-02 01:01:12 -05:00
|
|
|
|
2012-11-27 03:54:03 -05:00
|
|
|
filename_path = Pathname(filename).expand_path
|
2015-08-28 03:05:17 -04:00
|
|
|
begin
|
|
|
|
relative_path = filename_path.relative_path_from @options.root
|
|
|
|
rescue ArgumentError
|
|
|
|
relative_path = filename_path
|
|
|
|
end
|
2012-11-27 03:54:03 -05:00
|
|
|
|
2012-12-11 02:44:56 -05:00
|
|
|
if @options.page_dir and
|
|
|
|
relative_path.to_s.start_with? @options.page_dir.to_s then
|
|
|
|
relative_path =
|
|
|
|
relative_path.relative_path_from @options.page_dir
|
|
|
|
end
|
|
|
|
|
2012-11-27 03:54:03 -05:00
|
|
|
top_level = @store.add_file filename, relative_path.to_s
|
2004-01-02 01:01:12 -05:00
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
parser = RDoc::Parser.for top_level, filename, content, @options, @stats
|
2008-01-07 01:56:46 -05:00
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
return unless parser
|
2003-12-01 02:12:49 -05:00
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
parser.scan
|
2010-12-19 22:22:49 -05:00
|
|
|
|
|
|
|
# restart documentation for the classes & modules found
|
|
|
|
top_level.classes_or_modules.each do |cm|
|
|
|
|
cm.done_documenting = false
|
|
|
|
end
|
|
|
|
|
|
|
|
top_level
|
|
|
|
|
2012-11-26 23:28:14 -05:00
|
|
|
rescue Errno::EACCES => e
|
|
|
|
$stderr.puts <<-EOF
|
|
|
|
Unable to read #{filename}, #{e.message}
|
|
|
|
|
|
|
|
Please check the permissions for this file. Perhaps you do not have access to
|
|
|
|
it or perhaps the original author's permissions are to restrictive. If the
|
|
|
|
this is not your library please report a bug to the author.
|
|
|
|
EOF
|
2010-04-01 03:45:16 -04:00
|
|
|
rescue => e
|
|
|
|
$stderr.puts <<-EOF
|
|
|
|
Before reporting this, could you check that the file you're documenting
|
2010-12-19 22:22:49 -05:00
|
|
|
has proper syntax:
|
|
|
|
|
|
|
|
#{Gem.ruby} -c #{filename}
|
|
|
|
|
|
|
|
RDoc is not a full Ruby parser and will fail when fed invalid ruby programs.
|
2008-01-07 01:56:46 -05:00
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
The internal error was:
|
2008-01-13 22:34:05 -05:00
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
\t(#{e.class}) #{e.message}
|
2004-01-02 01:01:12 -05:00
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
EOF
|
2003-12-01 02:12:49 -05:00
|
|
|
|
2010-12-19 22:22:49 -05:00
|
|
|
$stderr.puts e.backtrace.join("\n\t") if $DEBUG_RDOC
|
2008-09-24 22:43:03 -04:00
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
raise e
|
|
|
|
nil
|
|
|
|
end
|
2003-12-01 02:12:49 -05:00
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
##
|
|
|
|
# Parse each file on the command line, recursively entering directories.
|
2003-12-01 02:12:49 -05:00
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
def parse_files files
|
|
|
|
file_list = gather_files files
|
2012-11-26 23:28:14 -05:00
|
|
|
@stats = RDoc::Stats.new @store, file_list.length, @options.verbosity
|
2008-01-13 22:34:05 -05:00
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
return [] if file_list.empty?
|
2008-01-13 22:34:05 -05:00
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
@stats.begin_adding
|
2008-02-11 20:27:52 -05:00
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
file_info = file_list.map do |filename|
|
|
|
|
@current = filename
|
|
|
|
parse_file filename
|
|
|
|
end.compact
|
2003-12-01 02:12:49 -05:00
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
@stats.done_adding
|
2008-07-17 20:46:16 -04:00
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
file_info
|
|
|
|
end
|
2008-07-17 20:46:16 -04:00
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
##
|
2012-11-26 23:28:14 -05:00
|
|
|
# Removes file extensions known to be unparseable from +files+ and TAGS
|
|
|
|
# files for emacs and vim.
|
2003-12-01 02:12:49 -05:00
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
def remove_unparseable files
|
|
|
|
files.reject do |file|
|
2012-11-26 23:28:14 -05:00
|
|
|
file =~ /\.(?:class|eps|erb|scpt\.txt|ttf|yml)$/i or
|
|
|
|
(file =~ /tags$/i and
|
|
|
|
open(file, 'rb') { |io|
|
|
|
|
io.read(100) =~ /\A(\f\n[^,]+,\d+$|!_TAG_)/
|
|
|
|
})
|
2003-12-01 02:12:49 -05:00
|
|
|
end
|
2010-04-01 03:45:16 -04:00
|
|
|
end
|
2003-12-01 02:12:49 -05:00
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
##
|
2011-02-01 19:32:30 -05:00
|
|
|
# Generates documentation or a coverage report depending upon the settings
|
|
|
|
# in +options+.
|
|
|
|
#
|
|
|
|
# +options+ can be either an RDoc::Options instance or an array of strings
|
|
|
|
# equivalent to the strings that would be passed on the command line like
|
|
|
|
# <tt>%w[-q -o doc -t My\ Doc\ Title]</tt>. #document will automatically
|
|
|
|
# call RDoc::Options#finish if an options instance was given.
|
2010-04-01 03:45:16 -04:00
|
|
|
#
|
2011-02-01 19:32:30 -05:00
|
|
|
# For a list of options, see either RDoc::Options or <tt>rdoc --help</tt>.
|
|
|
|
#
|
|
|
|
# By default, output will be stored in a directory called "doc" below the
|
|
|
|
# current directory, so make sure you're somewhere writable before invoking.
|
|
|
|
|
|
|
|
def document options
|
2012-11-26 23:28:14 -05:00
|
|
|
self.store = RDoc::Store.new
|
2006-09-17 10:46:13 -04:00
|
|
|
|
2011-02-01 19:32:30 -05:00
|
|
|
if RDoc::Options === options then
|
|
|
|
@options = options
|
|
|
|
@options.finish
|
|
|
|
else
|
2012-11-26 23:28:14 -05:00
|
|
|
@options = load_options
|
2011-02-01 19:32:30 -05:00
|
|
|
@options.parse options
|
|
|
|
end
|
2008-01-07 01:56:46 -05:00
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
if @options.pipe then
|
|
|
|
handle_pipe
|
|
|
|
exit
|
|
|
|
end
|
2008-01-13 22:34:05 -05:00
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
@exclude = @options.exclude
|
2004-02-23 16:17:26 -05:00
|
|
|
|
2010-12-19 22:22:49 -05:00
|
|
|
unless @options.coverage_report then
|
|
|
|
@last_modified = setup_output_dir @options.op_dir, @options.force_update
|
|
|
|
end
|
2003-12-01 02:12:49 -05:00
|
|
|
|
2012-11-26 23:28:14 -05:00
|
|
|
@store.encoding = @options.encoding if @options.respond_to? :encoding
|
|
|
|
@store.dry_run = @options.dry_run
|
|
|
|
@store.main = @options.main_page
|
|
|
|
@store.title = @options.title
|
2012-12-13 02:58:47 -05:00
|
|
|
@store.path = @options.op_dir
|
2012-11-26 23:28:14 -05:00
|
|
|
|
2011-05-13 20:39:16 -04:00
|
|
|
@start_time = Time.now
|
2008-07-17 20:46:16 -04:00
|
|
|
|
2012-12-13 02:58:47 -05:00
|
|
|
@store.load_cache
|
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
file_info = parse_files @options.files
|
2006-09-17 10:46:13 -04:00
|
|
|
|
2010-12-19 22:22:49 -05:00
|
|
|
@options.default_title = "RDoc Documentation"
|
|
|
|
|
2012-11-26 23:28:14 -05:00
|
|
|
@store.complete @options.visibility
|
2006-09-17 10:46:13 -04:00
|
|
|
|
2011-02-01 19:32:30 -05:00
|
|
|
@stats.coverage_level = @options.coverage_report
|
|
|
|
|
2010-12-19 22:22:49 -05:00
|
|
|
if @options.coverage_report then
|
|
|
|
puts
|
2011-02-01 19:32:30 -05:00
|
|
|
|
2013-09-18 19:33:36 -04:00
|
|
|
puts @stats.report.accept RDoc::Markup::ToRdoc.new
|
2011-02-01 19:32:30 -05:00
|
|
|
elsif file_info.empty? then
|
2010-04-01 03:45:16 -04:00
|
|
|
$stderr.puts "\nNo newer files." unless @options.quiet
|
|
|
|
else
|
|
|
|
gen_klass = @options.generator
|
2006-09-17 10:46:13 -04:00
|
|
|
|
2012-11-26 23:28:14 -05:00
|
|
|
@generator = gen_klass.new @store, @options
|
2003-12-01 02:12:49 -05:00
|
|
|
|
2012-11-26 23:28:14 -05:00
|
|
|
generate
|
2010-04-01 03:45:16 -04:00
|
|
|
end
|
|
|
|
|
2011-05-12 19:41:35 -04:00
|
|
|
if @stats and (@options.coverage_report or not @options.quiet) then
|
2010-04-01 03:45:16 -04:00
|
|
|
puts
|
2013-09-18 19:33:36 -04:00
|
|
|
puts @stats.summary.accept RDoc::Markup::ToRdoc.new
|
2010-04-01 03:45:16 -04:00
|
|
|
end
|
|
|
|
|
2010-12-19 22:22:49 -05:00
|
|
|
exit @stats.fully_documented? if @options.coverage_report
|
2010-04-01 03:45:16 -04:00
|
|
|
end
|
|
|
|
|
2011-05-13 20:39:16 -04:00
|
|
|
##
|
|
|
|
# Generates documentation for +file_info+ (from #parse_files) into the
|
|
|
|
# output dir using the generator selected
|
|
|
|
# by the RDoc options
|
|
|
|
|
2012-11-26 23:28:14 -05:00
|
|
|
def generate
|
2011-05-13 20:39:16 -04:00
|
|
|
Dir.chdir @options.op_dir do
|
2012-11-26 23:28:14 -05:00
|
|
|
unless @options.quiet then
|
|
|
|
$stderr.puts "\nGenerating #{@generator.class.name.sub(/^.*::/, '')} format into #{Dir.pwd}..."
|
2011-05-13 20:39:16 -04:00
|
|
|
end
|
2012-11-26 23:28:14 -05:00
|
|
|
|
|
|
|
@generator.generate
|
|
|
|
update_output_dir '.', @start_time, @last_modified
|
2011-05-13 20:39:16 -04:00
|
|
|
end
|
|
|
|
end
|
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
##
|
|
|
|
# Removes a siginfo handler and replaces the previous
|
|
|
|
|
|
|
|
def remove_siginfo_handler
|
|
|
|
return unless Signal.list.key? 'INFO'
|
2003-12-01 02:12:49 -05:00
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
handler = @old_siginfo || 'DEFAULT'
|
|
|
|
|
|
|
|
trap 'INFO', handler
|
|
|
|
end
|
|
|
|
|
|
|
|
end
|
|
|
|
|
|
|
|
begin
|
|
|
|
require 'rubygems'
|
|
|
|
|
|
|
|
if Gem.respond_to? :find_files then
|
|
|
|
rdoc_extensions = Gem.find_files 'rdoc/discover'
|
|
|
|
|
|
|
|
rdoc_extensions.each do |extension|
|
|
|
|
begin
|
|
|
|
load extension
|
|
|
|
rescue => e
|
|
|
|
warn "error loading #{extension.inspect}: #{e.message} (#{e.class})"
|
2011-02-01 19:32:30 -05:00
|
|
|
warn "\t#{e.backtrace.join "\n\t"}" if $DEBUG
|
2003-12-01 02:12:49 -05:00
|
|
|
end
|
|
|
|
end
|
|
|
|
end
|
2010-04-01 03:45:16 -04:00
|
|
|
rescue LoadError
|
2003-12-01 02:12:49 -05:00
|
|
|
end
|
|
|
|
|
2010-04-01 03:45:16 -04:00
|
|
|
# require built-in generators after discovery in case they've been replaced
|
2010-04-02 09:13:45 -04:00
|
|
|
require 'rdoc/generator/darkfish'
|
|
|
|
require 'rdoc/generator/ri'
|
2014-09-04 21:41:25 -04:00
|
|
|
require 'rdoc/generator/pot'
|
2010-04-02 09:13:45 -04:00
|
|
|
|