class Puppet::Application::Doc

Attributes

manifest[RW]
unknown_args[RW]

Public Instance Methods

handle_unknown( opt, arg ) click to toggle source
    # File lib/puppet/application/doc.rb
117 def handle_unknown( opt, arg )
118   @unknown_args << {:opt => opt, :arg => arg }
119   true
120 end
help() click to toggle source
    # File lib/puppet/application/doc.rb
 56   def help
 57     <<-HELP
 58 
 59 puppet-doc(8) -- #{summary}
 60 ========
 61 
 62 SYNOPSIS
 63 --------
 64 Generates a reference for all Puppet types. Largely meant for internal
 65 Puppet Inc. use. (Deprecated)
 66 
 67 
 68 USAGE
 69 -----
 70 puppet doc [-h|--help] [-l|--list]
 71   [-r|--reference <reference-name>]
 72 
 73 
 74 DESCRIPTION
 75 -----------
 76 This deprecated command generates a Markdown document to stdout
 77 describing all installed Puppet types or all allowable arguments to
 78 puppet executables. It is largely meant for internal use and is used to
 79 generate the reference document available on the Puppet Inc. web site.
 80 
 81 For Puppet module documentation (and all other use cases) this command
 82 has been superseded by the "puppet-strings"
 83 module - see https://github.com/puppetlabs/puppetlabs-strings for more information.
 84 
 85 This command (puppet-doc) will be removed once the
 86 puppetlabs internal documentation processing pipeline is completely based
 87 on puppet-strings.
 88 
 89 OPTIONS
 90 -------
 91 
 92 * --help:
 93   Print this help message
 94 
 95 * --reference:
 96   Build a particular reference. Get a list of references by running
 97   'puppet doc --list'.
 98 
 99 
100 EXAMPLE
101 -------
102     $ puppet doc -r type > /tmp/type_reference.markdown
103 
104 
105 AUTHOR
106 ------
107 Luke Kanies
108 
109 
110 COPYRIGHT
111 ---------
112 Copyright (c) 2011 Puppet Inc., LLC Licensed under the Apache 2.0 License
113 
114 HELP
115   end
other() click to toggle source
    # File lib/puppet/application/doc.rb
153 def other
154   text = ""
155   with_contents = options[:references].length <= 1
156   exit_code = 0
157   require_relative '../../puppet/util/reference'
158   options[:references].sort_by(&:to_s).each do |name|
159     section = Puppet::Util::Reference.reference(name)
160     raise _("Could not find reference %{name}") % { name: name } unless section
161 
162     begin
163       # Add the per-section text, but with no ToC
164       text += section.send(options[:format], with_contents)
165     rescue => detail
166       Puppet.log_exception(detail, _("Could not generate reference %{name}: %{detail}") % { name: name, detail: detail })
167       exit_code = 1
168       next
169     end
170   end
171 
172   text += Puppet::Util::Reference.footer unless with_contents # We've only got one reference
173 
174   if options[:mode] == :pdf
175     Puppet::Util::Reference.pdf(text)
176   else
177     puts text
178   end
179 
180   exit exit_code
181 end
preinit() click to toggle source
   # File lib/puppet/application/doc.rb
 8 def preinit
 9   {:references => [], :mode => :text, :format => :to_markdown }.each do |name,value|
10     options[name] = value
11   end
12   @unknown_args = []
13   @manifest = false
14 end
rdoc() click to toggle source
    # File lib/puppet/application/doc.rb
126 def rdoc
127   exit_code = 0
128   files = []
129   unless @manifest
130     env = Puppet.lookup(:current_environment)
131     files += env.modulepath
132     files << ::File.dirname(env.manifest) if env.manifest != Puppet::Node::Environment::NO_MANIFEST
133   end
134   files += command_line.args
135   Puppet.info _("scanning: %{files}") % { files: files.inspect }
136 
137   Puppet.settings[:document_all] = options[:all] || false
138   begin
139     require_relative '../../puppet/util/rdoc'
140     if @manifest
141       Puppet::Util::RDoc.manifestdoc(files)
142     else
143       options[:outputdir] = "doc" unless options[:outputdir]
144       Puppet::Util::RDoc.rdoc(options[:outputdir], files, options[:charset])
145     end
146   rescue => detail
147     Puppet.log_exception(detail, _("Could not generate documentation: %{detail}") % { detail: detail })
148     exit_code = 1
149   end
150   exit exit_code
151 end
run_command() click to toggle source
    # File lib/puppet/application/doc.rb
122 def run_command
123   return [:rdoc].include?(options[:mode]) ? send(options[:mode]) : other
124 end
setup() click to toggle source
    # File lib/puppet/application/doc.rb
183 def setup
184   # sole manifest documentation
185   if command_line.args.size > 0
186     options[:mode] = :rdoc
187     @manifest = true
188   end
189 
190   if options[:mode] == :rdoc
191     setup_rdoc
192   else
193     setup_reference
194   end
195 
196   setup_logging
197 end
setup_logging() click to toggle source
    # File lib/puppet/application/doc.rb
226 def setup_logging
227   Puppet::Util::Log.level = :warning
228 
229   set_log_level
230 
231   Puppet::Util::Log.newdestination(:console)
232 end
setup_rdoc() click to toggle source
    # File lib/puppet/application/doc.rb
212 def setup_rdoc
213   # consume the unknown options
214   # and feed them as settings
215   if @unknown_args.size > 0
216     @unknown_args.each do |option|
217       # force absolute path for modulepath when passed on commandline
218       if option[:opt]=="--modulepath"
219         option[:arg] = option[:arg].split(::File::PATH_SEPARATOR).collect { |p| ::File.expand_path(p) }.join(::File::PATH_SEPARATOR)
220       end
221       Puppet.settings.handlearg(option[:opt], option[:arg])
222     end
223   end
224 end
setup_reference() click to toggle source
    # File lib/puppet/application/doc.rb
199 def setup_reference
200   if options[:all]
201     # Don't add dynamic references to the "all" list.
202     require_relative '../../puppet/util/reference'
203     refs = Puppet::Util::Reference.references(Puppet.lookup(:current_environment))
204     options[:references] = refs.reject do |ref|
205       Puppet::Util::Reference.reference(ref).dynamic?
206     end
207   end
208 
209   options[:references] << :type if options[:references].empty?
210 end
summary() click to toggle source
   # File lib/puppet/application/doc.rb
52 def summary
53   _("Generate Puppet references")
54 end