class RDoc::Generator::SDoc

Constants

CLASS_DIR
DESCRIPTION
FILE_DIR
GENERATOR_DIRS
RESOURCES_DIR
SEARCH_INDEX_FILE
TREE_FILE

Attributes

base_dir[R]
options[R]
store[R]

The RDoc::Store that is the source of the generated content

Public Instance Methods

class_dir() click to toggle source
# File lib/sdoc/generator.rb, line 181
def class_dir
  CLASS_DIR
end
file_dir() click to toggle source
# File lib/sdoc/generator.rb, line 185
def file_dir
  FILE_DIR
end
generate() click to toggle source
# File lib/sdoc/generator.rb, line 166
def generate
  @outputdir = Pathname.new(@options.op_dir).expand_path(@base_dir)
  @files = @store.all_files.sort
  @classes = @store.all_classes_and_modules.sort

  # Now actually write the output
  copy_resources
  generate_class_tree
  @json_index.generate
  generate_file_files
  generate_class_files
  generate_index_file
  generate_search_index if @options.search_index
end

Protected Instance Methods

add_class_search_index(index) click to toggle source

Add classes to search index array

# File lib/sdoc/generator.rb, line 247
def add_class_search_index(index)
  debug_msg "  generating class search index"
  @classes.uniq.select { |klass|
    klass.document_self_or_methods
  }.sort.each do |klass|
    modulename = klass.module? ? '' : (klass.superclass ? (String === klass.superclass ? klass.superclass : klass.superclass.full_name) : '')
    debug_msg "    #{klass.parent.full_name}::#{klass.name}"
    index[:searchIndex].push( search_string(klass.name) )
    index[:longSearchIndex].push( search_string(klass.parent.full_name) )
    files = klass.in_files.map{ |file| file.absolute_name }
    index[:info].push([
      klass.name,
      files.include?(klass.parent.full_name) ? files.first : klass.parent.full_name,
      klass.path,
      modulename ? " < #{modulename}" : '',
      snippet(klass.comment),
      TYPE_CLASS
    ])
  end
end
add_file_search_index(index) click to toggle source

Add files to search index array

# File lib/sdoc/generator.rb, line 226
def add_file_search_index(index)
  debug_msg "  generating file search index"

  @files.select { |file|
    file.document_self
  }.sort.each do |file|
    debug_msg "    #{file.path}"
    index[:searchIndex].push( search_string(file.name) )
    index[:longSearchIndex].push( search_string(file.path) )
    index[:info].push([
      file.name,
      file.path,
      file.path,
      '',
      snippet(file.comment),
      TYPE_FILE
    ])
  end
end
add_method_search_index(index) click to toggle source

Add methods to search index array

# File lib/sdoc/generator.rb, line 269
def add_method_search_index(index)
  debug_msg "  generating method search index"

  list = @classes.uniq.map do |klass|
    klass.method_list
  end.flatten.sort do |a, b|
    a.name == b.name ?
      a.parent.full_name <=> b.parent.full_name :
      a.name <=> b.name
  end.select do |method|
    method.document_self
  end.find_all do |m|
    m.visibility == :public || m.visibility == :protected ||
    m.force_documentation
  end

  list.each do |method|
    debug_msg "    #{method.full_name}"
    index[:searchIndex].push( search_string(method.name) + '()' )
    index[:longSearchIndex].push( search_string(method.parent.full_name) )
    index[:info].push([
      method.name,
      method.parent.full_name,
      method.path,
      method.params,
      snippet(method.comment),
      TYPE_METHOD
    ])
  end
end
copy_resources() click to toggle source

Copy all the resource files to output dir

# File lib/sdoc/generator.rb, line 366
def copy_resources
  resources_path = @template_dir + RESOURCES_DIR
  debug_msg "Copying #{resources_path}/** to #{@outputdir}/**"
  FileUtils.cp_r resources_path.to_s, @outputdir.to_s unless @options.dry_run
end
debug_msg( *msg ) click to toggle source

Output progress information if debugging is enabled

# File lib/sdoc/generator.rb, line 191
def debug_msg( *msg )
  return unless $DEBUG_RDOC
  $stderr.puts( *msg )
end
generate_class_files() click to toggle source

Generate a documentation file for each class

# File lib/sdoc/generator.rb, line 301
def generate_class_files
  debug_msg "Generating class documentation in #@outputdir"
  templatefile = @template_dir + 'class.rhtml'

  @classes.each do |klass|
    debug_msg "  working on %s (%s)" % [ klass.full_name, klass.path ]
    outfile     = @outputdir + klass.path
    rel_prefix  = @outputdir.relative_path_from( outfile.dirname )

    debug_msg "  rendering #{outfile}"
    self.render_template( templatefile, binding(), outfile ) unless @options.dry_run
  end
end
generate_class_tree() click to toggle source

Create class tree structure and write it as json

# File lib/sdoc/generator.rb, line 197
def generate_class_tree
  debug_msg "Generating class tree"
  topclasses = @classes.select {|klass| !(RDoc::ClassModule === klass.parent) }
  tree = generate_file_tree + generate_class_tree_level(topclasses)
  debug_msg "  writing class tree to %s" % TREE_FILE
  File.open(TREE_FILE, "w", 0644) do |f|
    f.write('var tree = '); f.write(tree.to_json(:max_nesting => 0))
  end unless @options.dry_run
end
generate_class_tree_level(classes, visited = {}) click to toggle source

Recursivly build class tree structure

# File lib/sdoc/generator.rb, line 208
def generate_class_tree_level(classes, visited = {})
  tree = []
  classes.select do |klass|
    !visited[klass] && klass.with_documentation?
  end.sort.each do |klass|
    visited[klass] = true
    item = [
      klass.name,
      klass.document_self_or_methods ? klass.path : '',
      klass.module? ? '' : (klass.superclass ? " < #{String === klass.superclass ? klass.superclass : klass.superclass.full_name}" : ''),
      generate_class_tree_level(klass.classes_and_modules, visited)
    ]
    tree << item
  end
  tree
end
generate_file_files() click to toggle source

Generate a documentation file for each file

# File lib/sdoc/generator.rb, line 316
def generate_file_files
  debug_msg "Generating file documentation in #@outputdir"
  templatefile = @template_dir + 'file.rhtml'

  @files.each do |file|
    outfile     = @outputdir + file.path
    debug_msg "  working on %s (%s)" % [ file.full_name, outfile ]
    rel_prefix  = @outputdir.relative_path_from( outfile.dirname )

    debug_msg "  rendering #{outfile}"
    self.render_template( templatefile, binding(), outfile ) unless @options.dry_run
  end
end
generate_file_tree() click to toggle source
# File lib/sdoc/generator.rb, line 386
def generate_file_tree
  if @files.length > 1
    @files_tree = FilesTree.new
    @files.each do |file|
      @files_tree.add(file.relative_name, file.path)
    end
    [['', '', 'files', generate_file_tree_level(@files_tree)]]
  else
    []
  end
end
generate_file_tree_level(tree) click to toggle source
# File lib/sdoc/generator.rb, line 398
def generate_file_tree_level(tree)
  tree.children.keys.sort.map do |name|
    child = tree.children[name]
    if String === child
      [name, child, '', []]
    else
      ['', '', name, generate_file_tree_level(child)]
    end
  end
end
generate_index_file() click to toggle source

Create index.html with frameset

# File lib/sdoc/generator.rb, line 348
def generate_index_file
  debug_msg "Generating index file in #@outputdir"
  templatefile = @template_dir + 'index.rhtml'
  outfile      = @outputdir + 'index.html'

  self.render_template( templatefile, binding(), outfile ) unless @options.dry_run
end
generate_search_index() click to toggle source

Generate file with links for the search engine

# File lib/sdoc/generator.rb, line 357
def generate_search_index
  debug_msg "Generating search engine index in #@outputdir"
  templatefile = @template_dir + 'search_index.rhtml'
  outfile      = @outputdir + 'panel/links.html'

  self.render_template( templatefile, binding(), outfile ) unless @options.dry_run
end
index_path() click to toggle source

Determines index path based on @options.main_page (or lack thereof)

# File lib/sdoc/generator.rb, line 331
def index_path
  # Break early to avoid a big if block when no main page is specified
  default = @files.first.path
  return default unless @options.main_page

  # Transform class name to file path
  if @options.main_page.include?("::")
    slashed = @options.main_page.sub(/^::/, "").gsub("::", "/")
    "%s/%s.html" % [ class_dir, slashed ]
  elsif file = @files.find { |f| f.full_name == @options.main_page }
    file.path
  else
    default
  end
end

Public Class Methods

new(store, options) click to toggle source
# File lib/sdoc/generator.rb, line 151
def initialize(store, options)
  @store   = store
  @options = options
  if @options.respond_to?('diagram=')
    @options.diagram = false
  end
  @options.pipe = true
  @github_url_cache = {}

  @template_dir = Pathname.new(options.template_dir)
  @base_dir = Pathname.pwd.expand_path

  @json_index = RDoc::Generator::JsonIndex.new self, options
end
setup_options(options) click to toggle source
# File lib/sdoc/generator.rb, line 123
def self.setup_options(options)
  @github = false
  options.search_index = true

  opt = options.option_parser
  opt.separator nil
  opt.separator "SDoc generator options:"
  opt.separator nil
  opt.on("--github", "-g",
          "Generate links to github.") do |value|
    options.github = true
  end
  opt.separator nil

  opt.on("--without-search", "-s",
          "Do not generate index file for search engines.",
          "SDoc uses javascript to reference individual documentation pages.",
          "Search engine crawlers are not smart enough to find all the",
          "referenced pages.",
          "To help them SDoc generates a static file with links to every",
          "documentation page. This file is not shown to the user."
          ) do
    options.search_index = false
  end
  opt.separator nil

end