Class: Puppet::Util::Reference

Inherits:
Object
  • Object
show all
Extended by:
InstanceLoader
Includes:
Puppet::Util, Docs
Defined in:
lib/vendor/puppet/util/reference.rb

Overview

Manage Reference Documentation.

Constant Summary

Constants included from Puppet::Util

AbsolutePathPosix, AbsolutePathWindows

Constants included from Docs

Docs::HEADER_LEVELS

Instance Attribute Summary collapse

Attributes included from Docs

#nodoc

Class Method Summary collapse

Instance Method Summary collapse

Methods included from InstanceLoader

instance_docs, instance_hash, instance_load, instance_loader, instance_loading?, loaded_instance, loaded_instances

Methods included from Puppet::Util

absolute_path?, activerecord_version, benchmark, binread, chuser, classproxy, #execfail, #execpipe, execute, execute_posix, execute_windows, logmethods, memory, path_to_uri, proxy, replace_file, safe_posix_fork, symbolize, symbolizehash, symbolizehash!, synchronize_on, thinmark, #threadlock, uri_to_path, wait_for_output, which, withumask

Methods included from POSIX

#get_posix_field, #gid, #idfield, #methodbyid, #methodbyname, #search_posix_field, #uid

Methods included from Docs

#desc, #dochook, #doctable, #markdown_definitionlist, #markdown_header, #nodoc?, #pad, scrub

Constructor Details

#initialize(name, options = {}, &block) ⇒ Reference

Returns a new instance of Reference.



83
84
85
86
87
88
89
90
91
92
93
94
95
96
 
# File 'lib/vendor/puppet/util/reference.rb', line 83

def initialize(name, options = {}, &block)
  @name = name
  options.each do |option, value|
    send(option.to_s + "=", value)
  end

  meta_def(:generate, &block)

  # Now handle the defaults
  @title ||= "#{@name.to_s.capitalize} Reference"
  @page ||= @title.gsub(/\s+/, '')
  @depth ||= 2
  @header ||= ""
end

Instance Attribute Details

#depth ⇒ Object

Returns the value of attribute depth.



68
69
70
 
# File 'lib/vendor/puppet/util/reference.rb', line 68

def depth
  @depth
end

#doc ⇒ Object 



71
72
73
74
75
76
77
 
# File 'lib/vendor/puppet/util/reference.rb', line 71

def doc
  if defined?(@doc)
    return "#{@name} - #{@doc}"
  else
    return @title
  end
end

#dynamic ⇒ Object

Returns the value of attribute dynamic.



68
69
70
 
# File 'lib/vendor/puppet/util/reference.rb', line 68

def dynamic
  @dynamic
end

#header ⇒ Object

Returns the value of attribute header.



68
69
70
 
# File 'lib/vendor/puppet/util/reference.rb', line 68

def header
  @header
end

#page ⇒ Object

Returns the value of attribute page.



68
69
70
 
# File 'lib/vendor/puppet/util/reference.rb', line 68

def page
  @page
end

#title ⇒ Object

Returns the value of attribute title.



68
69
70
 
# File 'lib/vendor/puppet/util/reference.rb', line 68

def title
  @title
end

Class Method Details



13
14
15
 
# File 'lib/vendor/puppet/util/reference.rb', line 13

def self.footer
  "\n\n----------------\n\n*This page autogenerated on #{Time.now}*\n"
end

.modes ⇒ Object 



17
18
19
 
# File 'lib/vendor/puppet/util/reference.rb', line 17

def self.modes
  %w{pdf text}
end

.newreference(name, options = {}, &block) ⇒ Object 



21
22
23
24
25
26
 
# File 'lib/vendor/puppet/util/reference.rb', line 21

def self.newreference(name, options = {}, &block)
  ref = self.new(name, options, &block)
  instance_hash(:reference)[name.intern] = ref

  ref
end

.page(*sections) ⇒ Object 



28
29
30
31
32
33
34
35
 
# File 'lib/vendor/puppet/util/reference.rb', line 28

def self.page(*sections)
  depth = 4
  # Use the minimum depth
  sections.each do |name|
    section = reference(name) or raise "Could not find section #{name}"
    depth = section.depth if section.depth < depth
  end
end

.pdf(text) ⇒ Object 



37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
 
# File 'lib/vendor/puppet/util/reference.rb', line 37

def self.pdf(text)
  puts "creating pdf"
  rst2latex = which('rst2latex') || which('rst2latex.py') ||
    raise("Could not find rst2latex")

  cmd = %{#{rst2latex} /tmp/puppetdoc.txt > /tmp/puppetdoc.tex}
  Puppet::Util.replace_file("/tmp/puppetdoc.txt") {|f| f.puts text }
  # There used to be an attempt to use secure_open / replace_file to secure
  # the target, too, but that did nothing: the race was still here.  We can
  # get exactly the same benefit from running this effort:
  File.unlink('/tmp/puppetdoc.tex') rescue nil
  output = %x{#{cmd}}
  unless $CHILD_STATUS == 0
    $stderr.puts "rst2latex failed"
    $stderr.puts output
    exit(1)
  end
  $stderr.puts output

  # Now convert to pdf
  Dir.chdir("/tmp") do
    %x{texi2pdf puppetdoc.tex >/dev/null 2>/dev/null}
  end

end

.references ⇒ Object 



63
64
65
66
 
# File 'lib/vendor/puppet/util/reference.rb', line 63

def self.references
  instance_loader(:reference).loadall
  loaded_instances(:reference).sort { |a,b| a.to_s <=> b.to_s }
end

Instance Method Details

#dynamic? ⇒ Boolean

Returns:

  • (Boolean) 


79
80
81
 
# File 'lib/vendor/puppet/util/reference.rb', line 79

def dynamic?
  self.dynamic
end

#indent(text, tab) ⇒ Object

Indent every line in the chunk except those which begin with ‘..’.



99
100
101
 
# File 'lib/vendor/puppet/util/reference.rb', line 99

def indent(text, tab)
  text.gsub(/(^|\A)/, tab).gsub(/^ +\.\./, "..")
end

#option(name, value) ⇒ Object 



103
104
105
 
# File 'lib/vendor/puppet/util/reference.rb', line 103

def option(name, value)
  ":#{name.to_s.capitalize}: #{value}\n"
end

#text ⇒ Object 



107
108
109
 
# File 'lib/vendor/puppet/util/reference.rb', line 107

def text
  puts output
end

#to_markdown(withcontents = true) ⇒ Object 



111
112
113
114
115
116
117
118
119
120
121
122
123
 
# File 'lib/vendor/puppet/util/reference.rb', line 111

def to_markdown(withcontents = true)
  # First the header
  text = markdown_header(@title, 1)
  text << "\n\n**This page is autogenerated; any changes will get overwritten** *(last generated on #{Time.now.to_s})*\n\n"

  text << @header

  text << generate

  text << self.class.footer if withcontents

  text
end