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

DEFAULT_OPTIONS =

Default documenter options

{:highlight_source => true}

Instance Attribute Summary (collapse)

Instance Method Summary (collapse)

Constructor Details

- (Documenter) initialize(options = DEFAULT_OPTIONS)

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

- (Object) options

Documenter options



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

def options
  @options
end

Instance Method Details

- (Object) <<(source)

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

- (Array) current_scope

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

- (Object) current_scope=(scope) 



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

def current_scope=(scope)
  @current_scope = scope
end

- (Array) default_scope

Default documentation scope

Returns:

  • (Array) —

    default documentation scope



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

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

- (Jsus::Util::Tree) documented_sources

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

- (Object) documented_sources!

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

- (Object) generate(doc_dir = Dir.pwd)

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

- (Object) only(scope)

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

- (Object) or(scope)

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

- (Jsus::Util::Tree) tree

Tree with all sources

Returns:



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

def tree
  @tree ||= Tree.new
end