Class: Jsus::Util::Documenter

Inherits:
Object
  • Object
show all
Defined in:
lib/jsus/util/documenter.rb

Overview

Very opinionated documenter class. It uses Murdoc to generate the documentation using the template and stylesheet bundled with the jsus gem file. Also generates indices for navigation.

Constant Summary collapse

DEFAULT_OPTIONS =

Default documenter options

{:highlight_source => true}

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(options = DEFAULT_OPTIONS) ⇒ Documenter

Constructor. Accepts options as the argument.

Parameters:

  • options (Hash) (defaults to: DEFAULT_OPTIONS)

Options Hash (options):

  • :highlight_source (Boolean) —

    use syntax highlighting (via pygments)



18
19
20
21
22
23
 
# File 'lib/jsus/util/documenter.rb', line 18

def initialize(options = DEFAULT_OPTIONS)
  require "murdoc"
  self.options = options
rescue LoadError
  raise "You should install murdoc gem in order to produce documentation"
end

Instance Attribute Details

#options ⇒ Object

Documenter options



11
12
13
 
# File 'lib/jsus/util/documenter.rb', line 11

def options
  @options
end

Instance Method Details

#<<(source) ⇒ Object

Adds a source file to the documented source tree

Parameters:



54
55
56
57
58
59
60
61
62
63
 
# File 'lib/jsus/util/documenter.rb', line 54

def <<(source) # :nodoc:
  filename = File.basename(source.filename)
  if source.package

    tree["#{source.package.name}/#{filename}"] = source
  else
    tree["#{filename}"] = source
  end
  self
end

#current_scope ⇒ Array

Scope for documentation in pathspec format. See Jsus::Util::Tree::Node#find_children_matching

Returns:

  • (Array) —

    scope



74
75
76
 
# File 'lib/jsus/util/documenter.rb', line 74

def current_scope
  @current_scope ||= default_scope
end

#current_scope=(scope) ⇒ Object 



85
86
87
 
# File 'lib/jsus/util/documenter.rb', line 85

def current_scope=(scope)
  @current_scope = scope
end

#default_scope ⇒ Array

Returns default documentation scope.

Returns:

  • (Array) —

    default documentation scope



80
81
82
 
# File 'lib/jsus/util/documenter.rb', line 80

def default_scope
  ["/**/*"]
end

#documented_sources ⇒ Jsus::Util::Tree

Returns tree with documented sources only.

Returns:



112
113
114
 
# File 'lib/jsus/util/documenter.rb', line 112

def documented_sources
  @documented_sources ||= documented_sources!
end

#documented_sources! ⇒ Object

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

See Also:



118
119
120
121
122
123
 
# File 'lib/jsus/util/documenter.rb', line 118

def documented_sources!
  doctree = Tree.new
  current_scope.map {|pathspec| tree.find_nodes_matching(pathspec) }.
                flatten.each {|s| doctree.insert(s.full_path, s.value)}
  doctree
end

#generate(doc_dir = Dir.pwd) ⇒ Object

Generates documentation tree into the given directory.

Parameters:

  • doc_dir (String) (defaults to: Dir.pwd) —

    output directory



29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
 
# File 'lib/jsus/util/documenter.rb', line 29

def generate(doc_dir = Dir.pwd)
  #FileUtils.rm_rf(doc_dir)
  FileUtils.mkdir_p(doc_dir)
  template_path = File.dirname(__FILE__) + "/../../../markup"
  template = File.read("#{template_path}/template.haml")
  index_template = File.read("#{template_path}/index_template.haml")
  stylesheet_path = "#{template_path}/stylesheet.css"
  documented_sources.traverse(true) do |node|
    if node.value # leaf
      dir = doc_dir + File.dirname(node.full_path)
      FileUtils.mkdir_p(dir)
      file_from_contents(dir + "/#{node.name}.html", create_documentation_for_source(node.value, template))
    else
      dir = doc_dir + node.full_path
      FileUtils.mkdir_p(dir)
      FileUtils.cp(stylesheet_path, dir)
      file_from_contents(dir + "/index.html", create_index_for_node(node, index_template))
    end
  end
end

#only(scope) ⇒ Object

Sets documenter to exclusive scope for documentation. Exclusive scope overrides all the other scopes.

Parameters:

  • scope (Array, String) —

    documentation scope



93
94
95
96
97
 
# File 'lib/jsus/util/documenter.rb', line 93

def only(scope)
  result = clone
  result.current_scope = [scope].flatten
  result
end

#or(scope) ⇒ Object

Sets documenter to additive scope for documentation. Additive scopes match any of the pathspecs given

Parameters:

  • scope (Array, String) —

    documentation scope



104
105
106
107
108
 
# File 'lib/jsus/util/documenter.rb', line 104

def or(scope)
  result = clone
  result.current_scope = current_scope + [scope].flatten
  result
end

#tree ⇒ Jsus::Util::Tree

Returns tree with all sources.

Returns:



67
68
69
 
# File 'lib/jsus/util/documenter.rb', line 67

def tree
  @tree ||= Tree.new
end