Class: Puppet::Util::Reference

Inherits:
Object
  • Object
show all
Extended by:
InstanceLoader
Includes:
Puppet::Util, Docs
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, PUPPET_STACK_INSERTION_FRAME, RFC_3986_URI_REGEX

Constants included from SymbolicFileMode

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

Constants included from POSIX

POSIX::LOCALE_ENV_VARS, POSIX::USER_ENV_VARS

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_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, format_backtrace_array, format_puppetstack_frame, get_env, get_environment, logmethods, merge_environment, path_to_uri, pretty_backtrace, replace_file, resolve_stackframe, safe_posix_fork, set_env, skip_external_facts, symbolizehash, thinmark, uri_encode, uri_query_encode, uri_to_path, uri_unescape, which, withenv, withumask

Methods included from SymbolicFileMode

#normalize_symbolic_mode, #symbolic_mode_to_int, #valid_symbolic_mode?

Methods included from POSIX

#get_posix_field, #gid, groups_of, #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, title: nil, depth: nil, dynamic: nil, doc: nil, &block) ⇒ Reference

Returns a new instance of Reference.


79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
 
# File 'lib/puppet/util/reference.rb', line 79

def initialize(name, title: nil, depth: nil, dynamic: nil, doc: nil, &block)
  @name = name
  @title = title
  @depth = depth
  @dynamic = dynamic
  @doc = doc

  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


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

def depth
  @depth
end

#doc ⇒ Object 


67
68
69
70
71
72
73
 
# File 'lib/puppet/util/reference.rb', line 67

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

#dynamic ⇒ Object

Returns the value of attribute dynamic


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

def dynamic
  @dynamic
end

#header ⇒ Object

Returns the value of attribute header


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

def header
  @header
end

#page ⇒ Object

Returns the value of attribute page


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

def page
  @page
end

#title ⇒ Object

Returns the value of attribute title


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

def title
  @title
end

Class Method Details

.modes ⇒ Object 


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

def self.modes
  %w{pdf text}
end

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


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

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

  ref
end

.page(*sections) ⇒ Object 


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

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 


33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
 
# File 'lib/puppet/util/reference.rb', line 33

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(environment) ⇒ Object 


59
60
61
62
 
# File 'lib/puppet/util/reference.rb', line 59

def self.references(environment)
  instance_loader(:reference).loadall(environment)
  loaded_instances(:reference).sort_by(&:to_s)
end

Instance Method Details

#dynamic? ⇒ Boolean

Returns:

  • (Boolean) 

75
76
77
 
# File 'lib/puppet/util/reference.rb', line 75

def dynamic?
  self.dynamic
end

#indent(text, tab) ⇒ Object

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


96
97
98
 
# File 'lib/puppet/util/reference.rb', line 96

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

#option(name, value) ⇒ Object 


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

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

#text ⇒ Object 


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

def text
  puts output
end

#to_markdown(withcontents = true) ⇒ Object 


108
109
110
111
112
113
114
115
116
117
118
 
# File 'lib/puppet/util/reference.rb', line 108

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**\n\n")

  text << @header

  text << generate

  text
end