Class: RDoc::Generator::Darkfish
Relationships & Source Files | |
Super Chains via Extension / Inclusion / Inheritance | |
Instance Chain:
self,
ERB::Util
|
|
Inherits: | Object |
Defined in: | lib/rdoc/generator/darkfish.rb |
Overview
Darkfish
RDoc HTML Generator
$Id: darkfish.rb 52 2009-01-07 02:08:11Z deveiant $
Author/s
-
Michael Granger (ged@FaerieMUD.org)
Contributors
-
Mahlon E. Smith (mahlon@martini.nu)
-
Eric Hodel (drbrain@segment7.net)
License
Copyright © 2007, 2008, Michael Granger. All rights reserved.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
-
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
-
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
-
Neither the name of the author/s, nor the names of the project’s contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Attributions
Darkfish
uses the / Silk Icons set by Mark James.
Constant Summary
-
BUILTIN_STYLE_ITEMS =
Internal use only
Stylesheets, fonts, etc. that are included in
::RDoc::RDoc
.%w[ css/fonts.css fonts/Lato-Light.ttf fonts/Lato-LightItalic.ttf fonts/Lato-Regular.ttf fonts/Lato-RegularItalic.ttf fonts/SourceCodePro-Bold.ttf fonts/SourceCodePro-Regular.ttf css/rdoc.css ]
-
DESCRIPTION =
Description of this generator
'HTML generator, written by Michael Granger'
-
GENERATOR_DIR =
Path to this file’s parent directory. Used to find templates and other resources.
File.join 'rdoc', 'generator'
-
SVNID_PATTERN =
%q$Id: darkfish.rb 52 2009-01-07 02:08:11Z deveiant $“
/ \$Id:\s (\S+)\s # filename (\d+)\s # rev (\d{4}-\d{2}-\d{2})\s # Date (YYYY-MM-DD) (\d{2}:\d{2}:\d{2}Z)\s # Time (HH:MM:SSZ) (\w+)\s # committer \$$ /x
-
VERSION =
Release Version
'3'
Class Method Summary
-
.new(store, options) ⇒ Darkfish
constructor
Initialize a few instance variables before we start.
Instance Attribute Summary
-
#asset_rel_path
rw
The relative path to style sheets and javascript.
-
#base_dir
readonly
The path to generate files into, combined with
--op
from the options for a full path. -
#classes
readonly
Classes and modules to be used by this generator, not necessarily displayed.
-
#dry_run
rw
No files will be written when dry_run is true.
-
#file_output
rw
When false the generate methods return a String instead of writing to a file.
-
#files
readonly
Files to be displayed by this generator.
-
#json_index
readonly
The JSON index generator for this
Darkfish
generator. -
#methods
readonly
Methods to be displayed by this generator.
-
#modsort
readonly
Sorted list of classes and modules to be displayed by this generator.
-
#outputdir
readonly
The output directory.
-
#store
readonly
The
::RDoc::Store
that is the source of the generated content. -
#template_dir
readonly
Internal use only
The directory where the template files live.
Instance Method Summary
-
#assemble_template(body_file)
Creates a template from its components and the
body_file
. -
#class_dir
Directory where generated class HTML files live relative to the output dir.
-
#copy_static
Copies static files from the static_path into the output directory.
-
#debug_msg(*msg)
Output progress information if debugging is enabled.
-
#excerpt(content)
Returns an excerpt of the content for usage in meta description tags.
-
#file_dir
Directory where generated class HTML files live relative to the output dir.
-
#gen_sub_directories
Create the directories the generated docs will live in if they don’t already exist.
-
#generate
Build the initial indices and output objects based on an array of
::RDoc::TopLevel
objects containing the extracted information. - #generate_ancestor_list(ancestors, klass)
-
#generate_class(klass, template_file = nil)
Generates a class file for
klass
-
#generate_class_files
Generate a documentation file for each class and module.
-
#generate_file_files
Generate a documentation file for each file.
-
#generate_index
Generate an index page which lists all the classes which are documented.
-
#generate_page(file)
Generate a page file for
file
-
#generate_servlet_not_found(message)
Generates the 404 page for the
::RDoc::RDoc
servlet. -
#generate_servlet_root(installed)
Generates the servlet root page for the
::RDoc::RDoc
servlet. -
#generate_table_of_contents
Generate an index page which lists all the classes which are documented.
-
#get_sorted_module_list(classes)
Return a list of the documented modules sorted by salience first, then by name.
-
#get_svninfo(klass)
Try to extract Subversion information out of the first constant whose value looks like a subversion Id tag.
-
#render(file_name)
Renders the ERb contained in
file_name
relative to the template directory and returns the result based on the current context. -
#render_template(template_file, out_file = nil)
Load and render the erb template in the given
template_file
and write it out toout_file
. -
#setup
Prepares for generation of output from the current directory.
-
#template_for(file, page = true, klass = ERB)
Retrieves a cache template for
file
, if present, or fills the cache. -
#template_result(template, context, template_file)
Creates the result for
template
withcontext
. -
#time_delta_string(seconds)
Return a string describing the amount of time in the given number of seconds in terms a human can understand easily.
-
#write_style_sheet
Copy over the stylesheet into the appropriate place in the output directory.
- #install_rdoc_static_file(source, destination, options) Internal use only
Constructor Details
.new(store, options) ⇒ Darkfish
Initialize a few instance variables before we start
# File 'lib/rdoc/generator/darkfish.rb', line 159
def initialize store, @store = store @options = @asset_rel_path = '' @base_dir = Pathname.pwd. @dry_run = @options.dry_run @file_output = true @template_dir = Pathname.new .template_dir @template_cache = {} @classes = nil @context = nil @files = nil @methods = nil @modsort = nil @json_index = RDoc::Generator::JsonIndex.new self, end
Instance Attribute Details
#asset_rel_path (rw)
The relative path to style sheets and javascript. By default this is set the same as the rel_prefix.
# File 'lib/rdoc/generator/darkfish.rb', line 96
attr_accessor :asset_rel_path
#base_dir (readonly)
The path to generate files into, combined with --op
from the options for a full path.
# File 'lib/rdoc/generator/darkfish.rb', line 102
attr_reader :base_dir
#classes (readonly)
Classes and modules to be used by this generator, not necessarily displayed. See also #modsort
# File 'lib/rdoc/generator/darkfish.rb', line 108
attr_reader :classes
#dry_run (rw)
No files will be written when dry_run is true.
# File 'lib/rdoc/generator/darkfish.rb', line 113
attr_accessor :dry_run
#file_output (rw)
When false the generate methods return a String instead of writing to a file. The default is true.
# File 'lib/rdoc/generator/darkfish.rb', line 119
attr_accessor :file_output
#files (readonly)
Files to be displayed by this generator
# File 'lib/rdoc/generator/darkfish.rb', line 124
attr_reader :files
#json_index (readonly)
The JSON index generator for this Darkfish
generator
# File 'lib/rdoc/generator/darkfish.rb', line 129
attr_reader :json_index
#methods (readonly)
Methods to be displayed by this generator
# File 'lib/rdoc/generator/darkfish.rb', line 134
attr_reader :methods
#modsort (readonly)
Sorted list of classes and modules to be displayed by this generator
# File 'lib/rdoc/generator/darkfish.rb', line 139
attr_reader :modsort
#outputdir (readonly)
The output directory
# File 'lib/rdoc/generator/darkfish.rb', line 154
attr_reader :outputdir
#store (readonly)
The ::RDoc::Store
that is the source of the generated content
# File 'lib/rdoc/generator/darkfish.rb', line 144
attr_reader :store
#template_dir (readonly)
The directory where the template files live
# File 'lib/rdoc/generator/darkfish.rb', line 149
attr_reader :template_dir # :nodoc:
Instance Method Details
#assemble_template(body_file)
Creates a template from its components and the body_file
.
For backwards compatibility, if body_file
contains “<html” the body is used directly.
# File 'lib/rdoc/generator/darkfish.rb', line 675
def assemble_template body_file body = body_file.read return body if body =~ /<html/ head_file = @template_dir + '_head.rhtml' <<-TEMPLATE <!DOCTYPE html> <html> <head> #{head_file.read} #{body} TEMPLATE end
#class_dir
Directory where generated class HTML files live relative to the output dir.
# File 'lib/rdoc/generator/darkfish.rb', line 191
def class_dir nil end
#copy_static
Copies static files from the static_path into the output directory
# File 'lib/rdoc/generator/darkfish.rb', line 265
def copy_static return if @options.static_path.empty? = { :verbose => $DEBUG_RDOC, :noop => @dry_run } @options.static_path.each do |path| unless File.directory? path then FileUtils.install path, @outputdir, ** .merge(:mode => 0644) next end Dir.chdir path do Dir[File.join('**', '*')].each do |entry| dest_file = @outputdir + entry if File.directory? entry then FileUtils.mkdir_p entry, ** else FileUtils.install entry, dest_file, ** .merge(:mode => 0644) end end end end end
#debug_msg(*msg)
Output progress information if debugging is enabled
# File 'lib/rdoc/generator/darkfish.rb', line 182
def debug_msg *msg return unless $DEBUG_RDOC $stderr.puts(*msg) end
#excerpt(content)
Returns an excerpt of the content for usage in meta description tags
# File 'lib/rdoc/generator/darkfish.rb', line 784
def excerpt(content) text = content.is_a?(RDoc::Comment) ? content.text : content # Match from a capital letter to the first period, discarding any links, so # that we don't end up matching badges in the README first_paragraph_match = text.match(/[A-Z][^\.:\/]+\./) return text[0...150].gsub(/\n/, " ").squeeze(" ") unless first_paragraph_match extracted_text = first_paragraph_match[0] second_paragraph = first_paragraph_match.post_match.match(/[A-Z][^\.:\/]+\./) extracted_text << " " << second_paragraph[0] if second_paragraph extracted_text[0...150].gsub(/\n/, " ").squeeze(" ") end
#file_dir
Directory where generated class HTML files live relative to the output dir.
# File 'lib/rdoc/generator/darkfish.rb', line 199
def file_dir nil end
#gen_sub_directories
Create the directories the generated docs will live in if they don’t already exist.
# File 'lib/rdoc/generator/darkfish.rb', line 207
def gen_sub_directories @outputdir.mkpath end
#generate
Build the initial indices and output objects based on an array of ::RDoc::TopLevel
objects containing the extracted information.
# File 'lib/rdoc/generator/darkfish.rb', line 241
def generate setup write_style_sheet generate_index generate_class_files generate_file_files generate_table_of_contents @json_index.generate @json_index.generate_gzipped copy_static rescue => e debug_msg "%s: %s\n %s" % [ e.class.name, e., e.backtrace.join("\n ") ] raise end
#generate_ancestor_list(ancestors, klass)
[ GitHub ]# File 'lib/rdoc/generator/darkfish.rb', line 799
def generate_ancestor_list(ancestors, klass) return '' if ancestors.empty? ancestor = ancestors.shift content = +'<ul><li>' if ancestor.is_a?(RDoc::NormalClass) content << "<a href=\"#{klass.aref_to ancestor.path}\">#{ancestor.full_name}</a>" else content << ancestor.to_s end # Recursively call the method for the remaining ancestors content << generate_ancestor_list(ancestors, klass) content << '</li></ul>' end
#generate_class(klass, template_file = nil)
Generates a class file for klass
# File 'lib/rdoc/generator/darkfish.rb', line 337
def generate_class klass, template_file = nil setup current = klass template_file ||= @template_dir + 'class.rhtml' debug_msg " working on %s (%s)" % [klass.full_name, klass.path] out_file = @outputdir + klass.path rel_prefix = @outputdir.relative_path_from out_file.dirname search_index_rel_prefix = rel_prefix search_index_rel_prefix += @asset_rel_path if @file_output asset_rel_prefix = rel_prefix + @asset_rel_path svninfo = get_svninfo(current) @title = "#{klass.type} #{klass.full_name} - #{@options.title}" debug_msg " rendering #{out_file}" render_template template_file, out_file do |io| here = binding # suppress 1.9.3 warning here.local_variable_set(:asset_rel_prefix, asset_rel_prefix) here.local_variable_set(:svninfo, svninfo) here end end
#generate_class_files
Generate a documentation file for each class and module
# File 'lib/rdoc/generator/darkfish.rb', line 368
def generate_class_files setup template_file = @template_dir + 'class.rhtml' template_file = @template_dir + 'classpage.rhtml' unless template_file.exist? return unless template_file.exist? debug_msg "Generating class documentation in #{@outputdir}" current = nil @classes.each do |klass| current = klass generate_class klass, template_file end rescue => e error = RDoc::Error.new \ "error generating #{current.path}: #{e.} (#{e.class})" error.set_backtrace e.backtrace raise error end
#generate_file_files
Generate a documentation file for each file
# File 'lib/rdoc/generator/darkfish.rb', line 395
def generate_file_files setup page_file = @template_dir + 'page.rhtml' fileinfo_file = @template_dir + 'fileinfo.rhtml' # for legacy templates filepage_file = @template_dir + 'filepage.rhtml' unless page_file.exist? or fileinfo_file.exist? return unless page_file.exist? or fileinfo_file.exist? or filepage_file.exist? debug_msg "Generating file documentation in #{@outputdir}" out_file = nil current = nil @files.each do |file| current = file if file.text? and page_file.exist? then generate_page file next end template_file = nil out_file = @outputdir + file.path debug_msg " working on %s (%s)" % [file.full_name, out_file] rel_prefix = @outputdir.relative_path_from out_file.dirname search_index_rel_prefix = rel_prefix search_index_rel_prefix += @asset_rel_path if @file_output asset_rel_prefix = rel_prefix + @asset_rel_path unless filepage_file then if file.text? then next unless page_file.exist? template_file = page_file @title = file.page_name else next unless fileinfo_file.exist? template_file = fileinfo_file @title = "File: #{file.base_name}" end end @title += " - #{@options.title}" template_file ||= filepage_file render_template template_file, out_file do |io| here = binding # suppress 1.9.3 warning here.local_variable_set(:asset_rel_prefix, asset_rel_prefix) here.local_variable_set(:current, current) here end end rescue => e error = RDoc::Error.new "error generating #{out_file}: #{e.} (#{e.class})" error.set_backtrace e.backtrace raise error end
#generate_index
Generate an index page which lists all the classes which are documented.
# File 'lib/rdoc/generator/darkfish.rb', line 303
def generate_index setup template_file = @template_dir + 'index.rhtml' return unless template_file.exist? debug_msg "Rendering the index page..." out_file = @base_dir + @options.op_dir + 'index.html' rel_prefix = @outputdir.relative_path_from out_file.dirname search_index_rel_prefix = rel_prefix search_index_rel_prefix += @asset_rel_path if @file_output asset_rel_prefix = rel_prefix + @asset_rel_path @title = @options.title render_template template_file, out_file do |io| here = binding # suppress 1.9.3 warning here.local_variable_set(:asset_rel_prefix, asset_rel_prefix) here end rescue => e error = RDoc::Error.new \ "error generating index.html: #{e.} (#{e.class})" error.set_backtrace e.backtrace raise error end
#generate_page(file)
Generate a page file for file
# File 'lib/rdoc/generator/darkfish.rb', line 464
def generate_page file setup template_file = @template_dir + 'page.rhtml' out_file = @outputdir + file.path debug_msg " working on %s (%s)" % [file.full_name, out_file] rel_prefix = @outputdir.relative_path_from out_file.dirname search_index_rel_prefix = rel_prefix search_index_rel_prefix += @asset_rel_path if @file_output current = file asset_rel_prefix = rel_prefix + @asset_rel_path @title = "#{file.page_name} - #{@options.title}" debug_msg " rendering #{out_file}" render_template template_file, out_file do |io| here = binding # suppress 1.9.3 warning here.local_variable_set(:current, current) here.local_variable_set(:asset_rel_prefix, asset_rel_prefix) here end end
#generate_servlet_not_found(message)
Generates the 404 page for the ::RDoc::RDoc
servlet
# File 'lib/rdoc/generator/darkfish.rb', line 493
def generate_servlet_not_found setup template_file = @template_dir + 'servlet_not_found.rhtml' return unless template_file.exist? debug_msg "Rendering the servlet 404 Not Found page..." rel_prefix = rel_prefix = '' search_index_rel_prefix = rel_prefix search_index_rel_prefix += @asset_rel_path if @file_output asset_rel_prefix = '' @title = 'Not Found' render_template template_file do |io| here = binding # suppress 1.9.3 warning here.local_variable_set(:asset_rel_prefix, asset_rel_prefix) here end rescue => e error = RDoc::Error.new \ "error generating servlet_not_found: #{e.} (#{e.class})" error.set_backtrace e.backtrace raise error end
#generate_servlet_root(installed)
Generates the servlet root page for the ::RDoc::RDoc
servlet
# File 'lib/rdoc/generator/darkfish.rb', line 526
def generate_servlet_root installed setup template_file = @template_dir + 'servlet_root.rhtml' return unless template_file.exist? debug_msg 'Rendering the servlet root page...' rel_prefix = '.' asset_rel_prefix = rel_prefix search_index_rel_prefix = asset_rel_prefix search_index_rel_prefix += @asset_rel_path if @file_output @title = 'Local RDoc Documentation' render_template template_file do |io| binding end rescue => e error = RDoc::Error.new \ "error generating servlet_root: #{e.} (#{e.class})" error.set_backtrace e.backtrace raise error end
#generate_table_of_contents
Generate an index page which lists all the classes which are documented.
# File 'lib/rdoc/generator/darkfish.rb', line 553
def generate_table_of_contents setup template_file = @template_dir + 'table_of_contents.rhtml' return unless template_file.exist? debug_msg "Rendering the Table of Contents..." out_file = @outputdir + 'table_of_contents.html' rel_prefix = @outputdir.relative_path_from out_file.dirname search_index_rel_prefix = rel_prefix search_index_rel_prefix += @asset_rel_path if @file_output asset_rel_prefix = rel_prefix + @asset_rel_path @title = "Table of Contents - #{@options.title}" render_template template_file, out_file do |io| here = binding # suppress 1.9.3 warning here.local_variable_set(:asset_rel_prefix, asset_rel_prefix) here end rescue => e error = RDoc::Error.new \ "error generating table_of_contents.html: #{e.} (#{e.class})" error.set_backtrace e.backtrace raise error end
#get_sorted_module_list(classes)
Return a list of the documented modules sorted by salience first, then by name.
#get_svninfo(klass)
Try to extract Subversion information out of the first constant whose value looks like a subversion Id tag. If no matching constant is found, and empty hash is returned.
# File 'lib/rdoc/generator/darkfish.rb', line 652
def get_svninfo klass constants = klass.constants or return {} constants.find { |c| c.value =~ SVNID_PATTERN } or return {} filename, rev, date, time, committer = $~.captures commitdate = Time.parse "#{date} #{time}" return { :filename => filename, :rev => Integer(rev), :commitdate => commitdate, :commitdelta => time_delta_string(Time.now - commitdate), :committer => committer, } end
#install_rdoc_static_file(source, destination, options)
# File 'lib/rdoc/generator/darkfish.rb', line 584
def install_rdoc_static_file source, destination, # :nodoc: return unless source.exist? begin FileUtils.mkdir_p File.dirname(destination), ** begin FileUtils.ln source, destination, ** rescue Errno::EEXIST FileUtils.rm destination retry end rescue FileUtils.cp source, destination, ** end end
#render(file_name)
Renders the ERb contained in file_name
relative to the template directory and returns the result based on the current context.
# File 'lib/rdoc/generator/darkfish.rb', line 696
def render file_name template_file = @template_dir + file_name template = template_for template_file, false, RDoc::ERBPartial template.filename = template_file.to_s template.result @context end
#render_template(template_file, out_file = nil)
Load and render the erb template in the given template_file
and write it out to out_file
.
Both template_file
and out_file
should be Pathname-like objects.
An io will be yielded which must be captured by binding in the caller.
# File 'lib/rdoc/generator/darkfish.rb', line 714
def render_template template_file, out_file = nil # :yield: io io_output = out_file && !@dry_run && @file_output erb_klass = io_output ? RDoc::ERBIO : ERB template = template_for template_file, true, erb_klass if io_output then debug_msg "Outputting to %s" % [out_file. ] out_file.dirname.mkpath out_file.open 'w', 0644 do |io| io.set_encoding @options.encoding @context = yield io template_result template, @context, template_file end else @context = yield nil output = template_result template, @context, template_file debug_msg " would have written %d characters to %s" % [ output.length, out_file. ] if @dry_run output end end
#setup
Prepares for generation of output from the current directory
# File 'lib/rdoc/generator/darkfish.rb', line 604
def setup return if instance_variable_defined? :@outputdir @outputdir = Pathname.new(@options.op_dir). @base_dir return unless @store @classes = @store.all_classes_and_modules.sort @files = @store.all_files.sort @methods = @classes.flat_map { |m| m.method_list }.sort @modsort = get_sorted_module_list @classes end
#template_for(file, page = true, klass = ERB)
Retrieves a cache template for file
, if present, or fills the cache.
# File 'lib/rdoc/generator/darkfish.rb', line 761
def template_for file, page = true, klass = ERB template = @template_cache[file] return template if template if page then template = assemble_template file erbout = 'io' else template = file.read template = template.encode @options.encoding file_var = File.basename(file).sub(/\..*/, '') erbout = "_erbout_#{file_var}" end template = klass.new template, trim_mode: '-', eoutvar: erbout @template_cache[file] = template template end
#template_result(template, context, template_file)
Creates the result for template
with context
. If an error is raised a Pathname template_file
will indicate the file where the error occurred.
#time_delta_string(seconds)
Return a string describing the amount of time in the given number of seconds in terms a human can understand easily.
# File 'lib/rdoc/generator/darkfish.rb', line 621
def time_delta_string seconds return 'less than a minute' if seconds < 60 return "#{seconds / 60} minute#{seconds / 60 == 1 ? '' : 's'}" if seconds < 3000 # 50 minutes return 'about one hour' if seconds < 5400 # 90 minutes return "#{seconds / 3600} hours" if seconds < 64800 # 18 hours return 'one day' if seconds < 86400 # 1 day return 'about one day' if seconds < 172800 # 2 days return "#{seconds / 86400} days" if seconds < 604800 # 1 week return 'about one week' if seconds < 1209600 # 2 week return "#{seconds / 604800} weeks" if seconds < 7257600 # 3 months return "#{seconds / 2419200} months" if seconds < 31536000 # 1 year return "#{seconds / 31536000} years" end
#write_style_sheet
Copy over the stylesheet into the appropriate place in the output directory.
# File 'lib/rdoc/generator/darkfish.rb', line 215
def write_style_sheet debug_msg "Copying static files" = { :verbose => $DEBUG_RDOC, :noop => @dry_run } BUILTIN_STYLE_ITEMS.each do |item| install_rdoc_static_file @template_dir + item, "./#{item}", end unless @options.template_stylesheets.empty? FileUtils.cp @options.template_stylesheets, '.', ** end Dir[(@template_dir + "{js,images}/**/*").to_s].each do |path| next if File.directory? path next if File.basename(path) =~ /^\./ dst = Pathname.new(path).relative_path_from @template_dir install_rdoc_static_file @template_dir + path, dst, end end