← Back to branch summary

~ubuntu-branches/ubuntu/oneiric/puppet/oneiric-security

« back to all changes in this revision

Viewing changes to bin/puppetdoc

  • Committer: Bazaar Package Importer
  • Author(s): Micah Anderson
  • Date: 2008-07-26 15:43:45 UTC
  • mto: (3.1.1 lenny) (1.3.1 upstream)
  • mto: This revision was merged to the branch mainline in revision 16.
  • Revision ID: james.westby@ubuntu.com-20080726154345-1fmgo76b4l72ulvc
Import upstream version 0.24.5

Show diffs side-by-side

added added

removed removed

Lines of Context:
bin/puppetdoc
8
8
#
9
9
# = Usage
10
10
#
11
 
#   puppetdoc [-h|--help] [-a|--arguments] [-t|--types]
 
11
#   puppetdoc [-a|--all] [-h|--help] [-m|--mode <text|pdf|trac> [-r|--reference <[type]|configuration|..>]
12
12
#
13
13
# = Description
14
14
#
19
19
#
20
20
# = Options
21
21
#
22
 
# arguments::
23
 
#   Print the documentation for arguments.
 
22
# all::
 
23
#   Output the docs for all of the reference types.
24
24
#
25
25
# help::
26
26
#   Print this help message
27
27
#
28
 
# types::
29
 
#   Print the argumenst for Puppet types.  This is the default.
 
28
# mode::
 
29
#   Determine the output mode.  Valid modes are 'text', 'trac', and 'pdf'.  Note that 'trac' mode only works on Reductive Labs servers.  The default mode is 'text'.
 
30
#
 
31
# reference::
 
32
#   Build a particular reference.  Get a list of references by running +puppetdoc --list+.
30
33
#
31
34
# = Example
32
35
#
33
 
#   $ puppetdoc > /tmp/reference.rst
 
36
#   $ puppetdoc -r type > /tmp/type_reference.rst
34
37
#
35
38
# = Author
36
39
#
38
41
#
39
42
# = Copyright
40
43
#
41
 
# Copyright (c) 2005 Reductive Labs, LLC
 
44
# Copyright (c) 2005-2007 Reductive Labs, LLC
42
45
# Licensed under the GNU Public License
43
46
 
44
47
require 'puppet'
 
48
require 'puppet/util/reference'
 
49
require 'puppet/network/handler'
45
50
require 'getoptlong'
46
51
 
47
52
result = GetoptLong.new(
 
53
        [ "--all",      "-a",                   GetoptLong::NO_ARGUMENT ],
 
54
        [ "--list",     "-l",                   GetoptLong::NO_ARGUMENT ],
 
55
        [ "--format",   "-f",                   GetoptLong::REQUIRED_ARGUMENT ],
48
56
        [ "--mode",     "-m",                   GetoptLong::REQUIRED_ARGUMENT ],
 
57
        [ "--reference",        "-r",                   GetoptLong::REQUIRED_ARGUMENT ],
49
58
        [ "--help",             "-h",                   GetoptLong::NO_ARGUMENT ]
50
59
)
51
60
 
52
61
debug = false
53
62
 
54
63
$tab = "    "
 
64
options = {:references => [], :mode => :text, :format => :to_rest}
55
65
 
56
 
mode = :types
 
66
Reference = Puppet::Util::Reference
57
67
 
58
68
begin
59
69
    result.each { |opt,arg|
60
70
        case opt
61
 
            when "--mode"
62
 
                mode = arg.intern
63
 
            when "--help"
64
 
                if Puppet.feature.usage?
65
 
                    RDoc::usage && exit
66
 
                else
67
 
                    puts "No help available unless you have RDoc::usage installed"
68
 
                    exit
69
 
                end
 
71
        when "--all"
 
72
            options[:all] = true
 
73
        when "--format"
 
74
            method = "to_%s" % arg
 
75
            if Reference.method_defined?(method)
 
76
                options[:format] = method
 
77
            else
 
78
                raise "Invalid output format %s" % arg
 
79
            end
 
80
        when "--mode"
 
81
            if Reference.modes.include?(arg)
 
82
                options[:mode] = arg.intern
 
83
            else
 
84
                raise "Invalid output mode %s" % arg
 
85
            end
 
86
        when "--list"
 
87
            puts Reference.references.collect { |r| Reference.reference(r).doc }.join("\n")
 
88
            exit(0)
 
89
        when "--reference"
 
90
            options[:references] << arg.intern
 
91
        when "--help"
 
92
            if Puppet.features.usage?
 
93
                RDoc::usage && exit
 
94
            else
 
95
                puts "No help available unless you have RDoc::usage installed"
 
96
                exit
 
97
            end
70
98
        end
71
99
    }
72
100
rescue GetoptLong::InvalidOption => detail
74
102
    exit(1)
75
103
end
76
104
 
77
 
include Puppet::Util::Docs
78
 
 
79
 
# Indent every line in the chunk except those which begin with '..'.
80
 
def indent(text, tab)
81
 
    return text.gsub(/(^|\A)/, tab).gsub(/^ +\.\./, "..")
82
 
end
83
 
 
84
 
def paramwrap(name, text, namevar = false)
85
 
    if namevar
86
 
        name = name.to_s + " (*namevar*)"
87
 
    end
88
 
 
89
 
    puts "#### %s" % name
90
 
    puts text
91
 
 
92
 
    puts ""
93
 
end
94
 
 
95
 
# Print the docs for arguments
96
 
def self.configref
97
 
    docs = {}
98
 
    Puppet.config.each do |name, object|
99
 
        docs[name] = object
100
 
    end
101
 
 
102
 
    docs.sort { |a, b|
103
 
        a[0].to_s <=> b[0].to_s
104
 
    }.each do |name, object|
105
 
        # Make each name an anchor
106
 
        puts %{#### <a name="#{name.to_s}">#{name.to_s}</a> (<em>#{object.section.to_s}</em>)}
107
 
 
108
 
        puts ""
109
 
        default = ""
110
 
        if val = object.value and val != ""
111
 
            default = "  ``%s``" % val
 
105
if options[:all]
 
106
    # Don't add dynamic references to the "all" list.
 
107
    options[:references] = Reference.references.reject do |ref|
 
108
        Reference.reference(ref).dynamic?
 
109
    end
 
110
end
 
111
 
 
112
if options[:references].empty?
 
113
    options[:references] << :type
 
114
end
 
115
 
 
116
case options[:mode]
 
117
when :trac
 
118
    options[:references].each do |name|
 
119
        section = Puppet::Util::Reference.reference(name) or raise "Could not find section %s" % name
 
120
        unless options[:mode] == :pdf
 
121
            section.trac
112
122
        end
 
123
    end
 
124
else
 
125
    text = ""
 
126
    if options[:references].length > 1
 
127
        with_contents = false
 
128
    else
 
129
        with_contents = true
 
130
    end
 
131
    exit_code = 0
 
132
    options[:references].sort { |a,b| a.to_s <=> b.to_s }.each do |name|
 
133
        raise "Could not find reference %s" % name unless section = Puppet::Util::Reference.reference(name)
 
134
 
113
135
        begin
114
 
            puts object.desc.gsub(/\n/, " ") + default
 
136
            # Add the per-section text, but with no ToC
 
137
            text += section.send(options[:format], with_contents)
115
138
        rescue => detail
116
139
            puts detail.backtrace
117
 
            puts detail
 
140
            $stderr.puts "Could not generate reference %s: %s" % [name, detail]
 
141
            exit_code = 1
 
142
            next
118
143
        end
119
 
        puts ""
120
 
    end
121
 
 
122
 
end
123
 
 
124
 
# Print the docs for types
125
 
def self.typedocs
126
 
    types = {}
127
 
    Puppet::Type.loadall
128
 
 
129
 
    Puppet::Type.eachtype { |type|
130
 
        next if type.name == :puppet
131
 
        next if type.name == :component
132
 
        types[type.name] = type
133
 
    }
134
 
 
135
 
    # Build a simple TOC
136
 
    puts "## Table of Contents"
137
 
    puts "1. <a href='#meta-parameters'>Meta-Parameters</a>"
138
 
    types.sort { |a, b| a[0].to_s <=> b[0].to_s }.each do |name, type|
139
 
        puts "1. <a href='#%s'>%s</a>" % [type.name, type.name.to_s.capitalize]
140
 
    end
141
 
 
142
 
    puts %{
143
 
<h2><a name="meta-parameters">Meta-Parameters</a></h2>
144
 
 
145
 
Metaparameters are parameters that work with any element; they are part of the
146
 
Puppet framework itself rather than being part of the implementation of any
147
 
given instance.  Thus, any defined metaparameter can be used with any instance
148
 
in your manifest, including defined components.
149
 
 
150
 
    }
151
 
    begin
152
 
        params = []
153
 
        Puppet::Type.eachmetaparam { |param|
154
 
            params << param
155
 
        }
156
 
 
157
 
        params.sort { |a,b|
158
 
            a.to_s <=> b.to_s
159
 
        }.each { |param|
160
 
            paramwrap(param.to_s, scrub(Puppet::Type.metaparamdoc(param)))
161
 
            #puts "<dt>" + param.to_s + "</dt>"
162
 
            #puts tab(1) + Puppet::Type.metaparamdoc(param).scrub.indent($tab)gsub(/\n\s*/,' ')
163
 
            #puts "<dd>"
164
 
            #puts indent(scrub(Puppet::Type.metaparamdoc(param)), $tab)
165
 
            #puts scrub(Puppet::Type.metaparamdoc(param))
166
 
            #puts "</dd>"
167
 
 
168
 
            #puts ""
169
 
        }
170
 
    rescue => detail
171
 
        puts detail.backtrace
172
 
        puts "incorrect metaparams: %s" % detail
173
 
        exit(1)
174
 
    end
175
 
 
176
 
    puts %{
177
 
## Types
178
 
 
179
 
- *namevar* is the parameter used to uniquely identify a type instance.
180
 
  This is the parameter that gets assigned when a string is provided before
181
 
  the colon in a type declaration.  In general, only developers will need to
182
 
  worry about which parameter is the ``namevar``.
183
 
  
184
 
  In the following code:
185
 
 
186
 
      file { "/etc/passwd":
187
 
          owner => root,
188
 
          group => root,
189
 
          mode => 644
190
 
      }
191
 
 
192
 
  "/etc/passwd" is considered the name of the file object (used for things like
193
 
  dependency handling), and because ``path`` is the namevar for ``file``, that
194
 
  string is assigned to the ``path`` parameter.
195
 
 
196
 
- *parameters* determine the specific configuration of the instance.  They either
197
 
  directly modify the system (internally, these are called states) or they affect
198
 
  how the instance behaves (e.g., adding a search path for ``exec`` instances
199
 
  or determining recursion on ``file`` instances).
200
 
 
201
 
When required binaries are specified for providers, fully qualifed paths
202
 
indicate that the binary must exist at that specific path and unqualified
203
 
binaries indicate that Puppet will search for the binary using the shell
204
 
path.
205
 
 
206
 
    }
207
 
 
208
 
    types.sort { |a,b|
209
 
        a.to_s <=> b.to_s
210
 
    }.each { |name,type|
211
 
 
212
 
        puts "
213
 
 
214
 
----------------
215
 
 
216
 
"
217
 
 
218
 
        puts "
219
 
<h2><a name='%s'>%s</a></h2>" % [name, name]
220
 
        puts scrub(type.doc) + "\n\n"
221
 
 
222
 
        docs = {}
223
 
        type.validstates.sort { |a,b|
224
 
            a.to_s <=> b.to_s
225
 
        }.reject { |sname|
226
 
            state = type.statebyname(sname)
227
 
            state.nodoc
228
 
        }.each { |sname|
229
 
            state = type.statebyname(sname)
230
 
 
231
 
            unless state
232
 
                raise "Could not retrieve state %s on type %s" % [sname, type.name]
233
 
            end
234
 
 
235
 
            doc = nil
236
 
            str = nil
237
 
            unless doc = state.doc
238
 
                $stderr.puts "No docs for %s[%s]" % [type, sname]
239
 
                next
240
 
            end
241
 
            doc = doc.dup
242
 
            str = doc
243
 
            str = scrub(str)
244
 
 
245
 
            #str = indent(str, $tab)
246
 
            docs[sname]  = str
247
 
        }
248
 
 
249
 
        puts "\n### %s Parameters\n" % name.to_s.capitalize
250
 
        type.parameters.sort { |a,b|
251
 
            a.to_s <=> b.to_s
252
 
        }.each { |name,param|
253
 
            #docs[name] = indent(scrub(type.paramdoc(name)), $tab)
254
 
            docs[name] = scrub(type.paramdoc(name))
255
 
        }
256
 
 
257
 
        docs.sort { |a, b|
258
 
            a[0].to_s <=> b[0].to_s
259
 
        }.each { |name, doc|
260
 
            namevar = type.namevar == name and name != :name
261
 
            paramwrap(name, doc, namevar)
262
 
        }
263
 
        puts "\n"
264
 
    }
265
 
end
266
 
 
267
 
def self.reports
268
 
    puts Puppet::Server::Report.reportdocs
269
 
end
270
 
 
271
 
def self.functions
272
 
    puts Puppet::Parser::Functions.functiondocs
273
 
end
274
 
 
275
 
unless respond_to?(mode)
276
 
    raise "Invalid mode %s" % mode
277
 
end
278
 
 
279
 
send(mode)
280
 
 
281
 
puts "
282
 
 
283
 
----------------
284
 
 
285
 
"
286
 
puts "\n*This page autogenerated on %s*" % Time.now
287
 
 
288
 
# $Id: puppetdoc 1846 2006-11-09 21:25:02Z luke $
 
144
    end
 
145
 
 
146
    unless with_contents # We've only got one reference
 
147
        text += Puppet::Util::Reference.footer
 
148
    end
 
149
 
 
150
    # Replace the trac links, since they're invalid everywhere else
 
151
    text.gsub!(/`\w+\s+([^`]+)`:trac:/) { |m| $1 }
 
152
 
 
153
    if options[:mode] == :pdf
 
154
        Puppet::Util::Reference.pdf(text)
 
155
    else
 
156
        puts text
 
157
    end
 
158
 
 
159
    exit exit_code
 
160
end
 
161
 
 
162