Class: Puppet::Util::Reference

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

Overview

Manage Reference Documentation.

Constant Summary

Constants included from Puppet::Util

AbsolutePathPosix, AbsolutePathWindows, DEFAULT_POSIX_MODE, DEFAULT_WINDOWS_MODE

Constants included from POSIX

POSIX::LOCALE_ENV_VARS, POSIX::USER_ENV_VARS

Constants included from SymbolicFileMode

SymbolicFileMode::SetGIDBit, SymbolicFileMode::SetUIDBit, SymbolicFileMode::StickyBit, SymbolicFileMode::SymbolicMode, SymbolicFileMode::SymbolicSpecialToBit

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?, benchmark, chuser, clear_environment, default_env, deterministic_rand, deterministic_rand_int, exit_on_fail, get_env, get_environment, logmethods, merge_environment, path_to_uri, pretty_backtrace, replace_file, safe_posix_fork, set_env, symbolizehash, thinmark, uri_encode, uri_query_encode, uri_to_path, which, withenv, withumask

Methods included from POSIX

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

Methods included from SymbolicFileMode

#normalize_symbolic_mode, #symbolic_mode_to_int, #valid_symbolic_mode?

Methods included from Docs

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

Methods included from MethodHelper

#requiredopts, #set_options, #symbolize_options

Constructor Details

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

Returns a new instance of Reference.



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

def initialize(name, options = {}, &block)
  @name = name
  set_options(options)

  meta_def(:generate, &block)

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

Instance Attribute Details

#depth ⇒ Object

Returns the value of attribute depth.



71
72
73
 
# File 'lib/puppet/util/reference.rb', line 71

def depth
  @depth
end

#doc ⇒ Object 



74
75
76
77
78
79
80
 
# File 'lib/puppet/util/reference.rb', line 74

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

#dynamic ⇒ Object

Returns the value of attribute dynamic.



71
72
73
 
# File 'lib/puppet/util/reference.rb', line 71

def dynamic
  @dynamic
end

#header ⇒ Object

Returns the value of attribute header.



71
72
73
 
# File 'lib/puppet/util/reference.rb', line 71

def header
  @header
end

#page ⇒ Object

Returns the value of attribute page.



71
72
73
 
# File 'lib/puppet/util/reference.rb', line 71

def page
  @page
end

#title ⇒ Object

Returns the value of attribute title.



71
72
73
 
# File 'lib/puppet/util/reference.rb', line 71

def title
  @title
end

Class Method Details



15
16
17
18
 
# File 'lib/puppet/util/reference.rb', line 15

def self.footer
  #TRANSLATORS message accompanied by date of generation
  "\n\n----------------\n\n*" + _("This page autogenerated on ") + "#{Time.now}*\n"
end

.modes ⇒ Object 



20
21
22
 
# File 'lib/puppet/util/reference.rb', line 20

def self.modes
  %w{pdf text}
end

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



24
25
26
27
28
29
 
# File 'lib/puppet/util/reference.rb', line 24

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

  ref
end

.page(*sections) ⇒ Object 



31
32
33
34
35
36
37
38
 
# File 'lib/puppet/util/reference.rb', line 31

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

.pdf(text) ⇒ Object 



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

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:
  Puppet::FileSystem.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 



66
67
68
69
 
# File 'lib/puppet/util/reference.rb', line 66

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) 


82
83
84
 
# File 'lib/puppet/util/reference.rb', line 82

def dynamic?
  self.dynamic
end

#indent(text, tab) ⇒ Object

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



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

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

#option(name, value) ⇒ Object 



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

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

#text ⇒ Object 



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

def text
  puts output
end

#to_markdown(withcontents = true) ⇒ Object 



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

def to_markdown(withcontents = true)
  # First the header
  text = markdown_header(@title, 1)
  #TRANSLATORS message accompanied by date of generation
  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