puppet-strings 1.1.1 → 1.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +4 -4
- data/CHANGELOG.md +21 -0
- data/Gemfile +4 -2
- data/README.md +53 -10
- data/codecov.yml +3 -0
- data/lib/puppet-strings.rb +30 -11
- data/lib/puppet-strings/json.rb +7 -0
- data/lib/puppet-strings/markdown.rb +35 -0
- data/lib/puppet-strings/markdown/base.rb +168 -0
- data/lib/puppet-strings/markdown/defined_type.rb +14 -0
- data/lib/puppet-strings/markdown/defined_types.rb +37 -0
- data/lib/puppet-strings/markdown/function.rb +52 -0
- data/lib/puppet-strings/markdown/functions.rb +38 -0
- data/lib/puppet-strings/markdown/puppet_class.rb +14 -0
- data/lib/puppet-strings/markdown/puppet_classes.rb +37 -0
- data/lib/puppet-strings/markdown/resource_type.rb +27 -0
- data/lib/puppet-strings/markdown/resource_types.rb +37 -0
- data/lib/puppet-strings/markdown/table_of_contents.rb +21 -0
- data/lib/puppet-strings/markdown/templates/classes_and_defines.erb +63 -0
- data/lib/puppet-strings/markdown/templates/function.erb +50 -0
- data/lib/puppet-strings/markdown/templates/resource_type.erb +114 -0
- data/lib/puppet-strings/markdown/templates/table_of_contents.erb +21 -0
- data/lib/puppet-strings/tasks/generate.rb +24 -5
- data/lib/puppet-strings/yard/code_objects/function.rb +3 -3
- data/lib/puppet-strings/yard/code_objects/type.rb +3 -1
- data/lib/puppet-strings/yard/handlers.rb +1 -0
- data/lib/puppet-strings/yard/handlers/puppet/function_handler.rb +1 -1
- data/lib/puppet-strings/yard/handlers/ruby/base.rb +1 -1
- data/lib/puppet-strings/yard/handlers/ruby/rsapi_handler.rb +141 -0
- data/lib/puppet/face/strings.rb +28 -7
- data/spec/acceptance/emit_json_options.rb +4 -4
- data/spec/acceptance/generate_markdown_spec.rb +49 -0
- data/spec/fixtures/unit/json/output.json +43 -0
- data/spec/fixtures/unit/markdown/output.md +383 -0
- data/spec/spec_helper.rb +19 -1
- data/spec/unit/puppet-strings/json_spec.rb +40 -0
- data/spec/unit/puppet-strings/markdown/base_spec.rb +146 -0
- data/spec/unit/puppet-strings/markdown_spec.rb +248 -0
- data/spec/unit/puppet-strings/yard/handlers/puppet/function_handler_spec.rb +16 -1
- data/spec/unit/puppet-strings/yard/handlers/ruby/provider_handler_spec.rb +1 -1
- data/spec/unit/puppet-strings/yard/handlers/ruby/rsapi_handler_spec.rb +213 -0
- metadata +38 -2
@@ -0,0 +1,383 @@
|
|
1
|
+
# Reference
|
2
|
+
|
3
|
+
## Classes
|
4
|
+
### Public Classes
|
5
|
+
* [`klass`](#klass): A simple class.
|
6
|
+
### Private Classes
|
7
|
+
* `noparams`: Overview for class noparams
|
8
|
+
## Defined types
|
9
|
+
* [`klass::dt`](#klassdt): A simple defined type.
|
10
|
+
## Resource types
|
11
|
+
* [`apt_key`](#apt_key): Example resource type using the new API.
|
12
|
+
* [`database`](#database): An example database server type.
|
13
|
+
## Functions
|
14
|
+
* [`func`](#func): A simple Puppet function.
|
15
|
+
* [`func3x`](#func3x): Documentation for an example 3.x function.
|
16
|
+
* [`func4x`](#func4x): An example 4.x function.
|
17
|
+
* [`func4x_1`](#func4x_1): An example 4.x function with only one signature.
|
18
|
+
## Classes
|
19
|
+
|
20
|
+
### klass
|
21
|
+
|
22
|
+
An overview for a simple class.
|
23
|
+
|
24
|
+
* **Since** 1.0.0
|
25
|
+
|
26
|
+
* **See also**
|
27
|
+
www.puppet.com
|
28
|
+
|
29
|
+
|
30
|
+
#### Examples
|
31
|
+
##### This is an example
|
32
|
+
```puppet
|
33
|
+
class { 'klass':
|
34
|
+
param1 => 1,
|
35
|
+
param3 => 'foo',
|
36
|
+
}
|
37
|
+
```
|
38
|
+
|
39
|
+
##### This is another example
|
40
|
+
```puppet
|
41
|
+
class { 'klass':
|
42
|
+
param1 => 1,
|
43
|
+
param3 => 'foo',
|
44
|
+
}
|
45
|
+
```
|
46
|
+
|
47
|
+
|
48
|
+
#### Parameters
|
49
|
+
|
50
|
+
The following parameters are available in the `klass` class.
|
51
|
+
|
52
|
+
##### `param1`
|
53
|
+
|
54
|
+
Data type: `Integer`
|
55
|
+
|
56
|
+
First param.
|
57
|
+
|
58
|
+
Default value: 1
|
59
|
+
|
60
|
+
##### `param2`
|
61
|
+
|
62
|
+
Data type: `Any`
|
63
|
+
|
64
|
+
Second param.
|
65
|
+
|
66
|
+
Options:
|
67
|
+
|
68
|
+
* **:opt1** `String`: something about opt1
|
69
|
+
* **:opt2** `Hash`: a hash of stuff
|
70
|
+
|
71
|
+
Default value: `undef`
|
72
|
+
|
73
|
+
##### `param3`
|
74
|
+
|
75
|
+
Data type: `String`
|
76
|
+
|
77
|
+
Third param.
|
78
|
+
|
79
|
+
Default value: 'hi'
|
80
|
+
|
81
|
+
|
82
|
+
## Defined types
|
83
|
+
|
84
|
+
### klass::dt
|
85
|
+
|
86
|
+
An overview for a simple defined type.
|
87
|
+
|
88
|
+
* **Since** 1.1.0
|
89
|
+
|
90
|
+
* **See also**
|
91
|
+
www.puppet.com
|
92
|
+
|
93
|
+
|
94
|
+
#### Examples
|
95
|
+
##### Here's an example of this type:
|
96
|
+
```puppet
|
97
|
+
klass::dt { 'foo':
|
98
|
+
param1 => 33,
|
99
|
+
param4 => false,
|
100
|
+
}
|
101
|
+
```
|
102
|
+
|
103
|
+
|
104
|
+
#### Parameters
|
105
|
+
|
106
|
+
The following parameters are available in the `klass::dt` defined type.
|
107
|
+
|
108
|
+
##### `param1`
|
109
|
+
|
110
|
+
Data type: `Integer`
|
111
|
+
|
112
|
+
First param.
|
113
|
+
|
114
|
+
Default value: 44
|
115
|
+
|
116
|
+
##### `param2`
|
117
|
+
|
118
|
+
Data type: `Any`
|
119
|
+
|
120
|
+
Second param.
|
121
|
+
|
122
|
+
Options:
|
123
|
+
|
124
|
+
* **:opt1** `String`: something about opt1
|
125
|
+
* **:opt2** `Hash`: a hash of stuff
|
126
|
+
|
127
|
+
##### `param3`
|
128
|
+
|
129
|
+
Data type: `String`
|
130
|
+
|
131
|
+
Third param.
|
132
|
+
|
133
|
+
Default value: 'hi'
|
134
|
+
|
135
|
+
##### `param4`
|
136
|
+
|
137
|
+
Data type: `Boolean`
|
138
|
+
|
139
|
+
Fourth param.
|
140
|
+
|
141
|
+
Default value: `true`
|
142
|
+
|
143
|
+
|
144
|
+
## Resource types
|
145
|
+
|
146
|
+
### apt_key
|
147
|
+
|
148
|
+
This type provides Puppet with the capabilities to manage GPG keys needed
|
149
|
+
by apt to perform package validation. Apt has it's own GPG keyring that can
|
150
|
+
be manipulated through the `apt-key` command.
|
151
|
+
**Autorequires**:
|
152
|
+
If Puppet is given the location of a key file which looks like an absolute
|
153
|
+
path this type will autorequire that file.
|
154
|
+
|
155
|
+
#### Examples
|
156
|
+
##### here's an example
|
157
|
+
```puppet
|
158
|
+
apt_key { '6F6B15509CF8E59E6E469F327F438280EF8D349F':
|
159
|
+
source => 'http://apt.puppetlabs.com/pubkey.gpg'
|
160
|
+
}
|
161
|
+
```
|
162
|
+
|
163
|
+
#### Properties
|
164
|
+
|
165
|
+
The following properties are available in the `apt_key` type.
|
166
|
+
|
167
|
+
##### `ensure`
|
168
|
+
|
169
|
+
Data type: `Enum[present, absent]`
|
170
|
+
|
171
|
+
Whether this apt key should be present or absent on the target system.
|
172
|
+
|
173
|
+
##### `created`
|
174
|
+
|
175
|
+
Data type: `String`
|
176
|
+
|
177
|
+
Date the key was created, in ISO format.
|
178
|
+
|
179
|
+
#### Parameters
|
180
|
+
|
181
|
+
The following parameters are available in the `apt_key` type.
|
182
|
+
|
183
|
+
##### `id`
|
184
|
+
|
185
|
+
namevar
|
186
|
+
|
187
|
+
Data type: `Variant[Pattern[/A(0x)?[0-9a-fA-F]{8}Z/], Pattern[/A(0x)?[0-9a-fA-F]{16}Z/], Pattern[/A(0x)?[0-9a-fA-F]{40}Z/]]`
|
188
|
+
_*this data type contains a regex that may not be accurately reflected in generated documentation_
|
189
|
+
|
190
|
+
The ID of the key you want to manage.
|
191
|
+
|
192
|
+
|
193
|
+
### database
|
194
|
+
|
195
|
+
An example database server type.
|
196
|
+
|
197
|
+
#### Examples
|
198
|
+
##### here's an example
|
199
|
+
```puppet
|
200
|
+
database { 'foo':
|
201
|
+
address => 'qux.baz.bar',
|
202
|
+
}
|
203
|
+
```
|
204
|
+
|
205
|
+
#### Properties
|
206
|
+
|
207
|
+
The following properties are available in the `database` type.
|
208
|
+
|
209
|
+
##### `ensure`
|
210
|
+
|
211
|
+
Valid values: present, absent, up, down
|
212
|
+
|
213
|
+
Aliases: "up"=>"present", "down"=>"absent"
|
214
|
+
|
215
|
+
What state the database should be in.
|
216
|
+
|
217
|
+
Default value: up
|
218
|
+
|
219
|
+
##### `file`
|
220
|
+
|
221
|
+
The database file to use.
|
222
|
+
|
223
|
+
##### `log_level`
|
224
|
+
|
225
|
+
Valid values: debug, warn, error
|
226
|
+
|
227
|
+
The log level to use.
|
228
|
+
|
229
|
+
Default value: warn
|
230
|
+
|
231
|
+
#### Parameters
|
232
|
+
|
233
|
+
The following parameters are available in the `database` type.
|
234
|
+
|
235
|
+
##### `address`
|
236
|
+
|
237
|
+
namevar
|
238
|
+
|
239
|
+
The database server name.
|
240
|
+
|
241
|
+
##### `encryption_key`
|
242
|
+
|
243
|
+
The encryption key to use.
|
244
|
+
|
245
|
+
##### `encrypt`
|
246
|
+
|
247
|
+
Valid values: `true`, `false`, yes, no
|
248
|
+
|
249
|
+
Whether or not to encrypt the database.
|
250
|
+
|
251
|
+
Default value: `false`
|
252
|
+
|
253
|
+
|
254
|
+
## Functions
|
255
|
+
|
256
|
+
### func
|
257
|
+
Type: Puppet Language
|
258
|
+
|
259
|
+
A simple Puppet function.
|
260
|
+
|
261
|
+
#### `func(Integer $param1, Any $param2, String $param3 = hi)`
|
262
|
+
|
263
|
+
A simple Puppet function.
|
264
|
+
|
265
|
+
Returns: `Undef` Returns nothing.
|
266
|
+
|
267
|
+
Raises:
|
268
|
+
* `SomeError` this is some error
|
269
|
+
|
270
|
+
##### `param1`
|
271
|
+
|
272
|
+
Data type: `Integer`
|
273
|
+
|
274
|
+
First param.
|
275
|
+
|
276
|
+
##### `param2`
|
277
|
+
|
278
|
+
Data type: `Any`
|
279
|
+
|
280
|
+
Second param.
|
281
|
+
|
282
|
+
##### `param3`
|
283
|
+
|
284
|
+
Data type: `String`
|
285
|
+
|
286
|
+
Third param.
|
287
|
+
|
288
|
+
Options:
|
289
|
+
|
290
|
+
* **:param3opt** `Array`: Something about this option
|
291
|
+
|
292
|
+
### func3x
|
293
|
+
Type: Ruby 3.x API
|
294
|
+
|
295
|
+
Documentation for an example 3.x function.
|
296
|
+
|
297
|
+
#### `func3x(String $param1, Integer $param2)`
|
298
|
+
|
299
|
+
Documentation for an example 3.x function.
|
300
|
+
|
301
|
+
Returns: `Undef`
|
302
|
+
|
303
|
+
##### `param1`
|
304
|
+
|
305
|
+
Data type: `String`
|
306
|
+
|
307
|
+
The first parameter.
|
308
|
+
|
309
|
+
##### `param2`
|
310
|
+
|
311
|
+
Data type: `Integer`
|
312
|
+
|
313
|
+
The second parameter.
|
314
|
+
|
315
|
+
### func4x
|
316
|
+
Type: Ruby 4.x API
|
317
|
+
|
318
|
+
An example 4.x function.
|
319
|
+
|
320
|
+
#### `func4x(Integer $param1, Any $param2, Optional[Array[String]] $param3)`
|
321
|
+
|
322
|
+
An overview for the first overload.
|
323
|
+
|
324
|
+
Returns: `Undef` Returns nothing.
|
325
|
+
|
326
|
+
##### `param1`
|
327
|
+
|
328
|
+
Data type: `Integer`
|
329
|
+
|
330
|
+
The first parameter.
|
331
|
+
|
332
|
+
##### `param2`
|
333
|
+
|
334
|
+
Data type: `Any`
|
335
|
+
|
336
|
+
The second parameter.
|
337
|
+
|
338
|
+
Options:
|
339
|
+
|
340
|
+
* **:option** `String`: an option
|
341
|
+
* **:option2** `String`: another option
|
342
|
+
|
343
|
+
##### `param3`
|
344
|
+
|
345
|
+
Data type: `Optional[Array[String]]`
|
346
|
+
|
347
|
+
The third parameter.
|
348
|
+
|
349
|
+
#### `func4x(Boolean $param, Callable &$block)`
|
350
|
+
|
351
|
+
An overview for the second overload.
|
352
|
+
|
353
|
+
Returns: `String` Returns a string.
|
354
|
+
|
355
|
+
##### `param`
|
356
|
+
|
357
|
+
Data type: `Boolean`
|
358
|
+
|
359
|
+
The first parameter.
|
360
|
+
|
361
|
+
##### `&block`
|
362
|
+
|
363
|
+
Data type: `Callable`
|
364
|
+
|
365
|
+
The block parameter.
|
366
|
+
|
367
|
+
### func4x_1
|
368
|
+
Type: Ruby 4.x API
|
369
|
+
|
370
|
+
An example 4.x function with only one signature.
|
371
|
+
|
372
|
+
#### `func4x_1(Integer $param1)`
|
373
|
+
|
374
|
+
An example 4.x function with only one signature.
|
375
|
+
|
376
|
+
Returns: `Undef` Returns nothing.
|
377
|
+
|
378
|
+
##### `param1`
|
379
|
+
|
380
|
+
Data type: `Integer`
|
381
|
+
|
382
|
+
The first parameter.
|
383
|
+
|
data/spec/spec_helper.rb
CHANGED
@@ -1,7 +1,26 @@
|
|
1
|
+
if ENV['COVERAGE'] == 'yes'
|
2
|
+
require 'simplecov'
|
3
|
+
require 'simplecov-console'
|
4
|
+
require 'codecov'
|
5
|
+
|
6
|
+
SimpleCov.formatters = [
|
7
|
+
SimpleCov::Formatter::HTMLFormatter,
|
8
|
+
SimpleCov::Formatter::Console,
|
9
|
+
SimpleCov::Formatter::Codecov,
|
10
|
+
]
|
11
|
+
SimpleCov.start do
|
12
|
+
track_files 'lib/**/*.rb'
|
13
|
+
|
14
|
+
add_filter '/spec'
|
15
|
+
end
|
16
|
+
end
|
17
|
+
|
1
18
|
require 'mocha'
|
2
19
|
require 'rspec'
|
3
20
|
require 'puppet/version'
|
4
21
|
require 'puppet-strings'
|
22
|
+
require 'puppet-strings/markdown'
|
23
|
+
require 'puppet-strings/markdown/base'
|
5
24
|
require 'puppet-strings/yard'
|
6
25
|
|
7
26
|
# Explicitly set up YARD once
|
@@ -21,4 +40,3 @@ RSpec.configure do |config|
|
|
21
40
|
YARD::Registry.clear
|
22
41
|
end
|
23
42
|
end
|
24
|
-
|
@@ -123,6 +123,46 @@ Puppet::Type.newtype(:database) do
|
|
123
123
|
defaultto 'warn'
|
124
124
|
end
|
125
125
|
end
|
126
|
+
|
127
|
+
Puppet::ResourceApi.register_type(
|
128
|
+
name: 'apt_key',
|
129
|
+
desc: <<-EOS,
|
130
|
+
@summary Example resource type using the new API.
|
131
|
+
@raise SomeError
|
132
|
+
This type provides Puppet with the capabilities to manage GPG keys needed
|
133
|
+
by apt to perform package validation. Apt has it's own GPG keyring that can
|
134
|
+
be manipulated through the `apt-key` command.
|
135
|
+
@example here's an example
|
136
|
+
apt_key { '6F6B15509CF8E59E6E469F327F438280EF8D349F':
|
137
|
+
source => 'http://apt.puppetlabs.com/pubkey.gpg'
|
138
|
+
}
|
139
|
+
|
140
|
+
**Autorequires**:
|
141
|
+
If Puppet is given the location of a key file which looks like an absolute
|
142
|
+
path this type will autorequire that file.
|
143
|
+
EOS
|
144
|
+
attributes: {
|
145
|
+
ensure: {
|
146
|
+
type: 'Enum[present, absent]',
|
147
|
+
desc: 'Whether this apt key should be present or absent on the target system.'
|
148
|
+
},
|
149
|
+
id: {
|
150
|
+
type: 'Variant[Pattern[/\A(0x)?[0-9a-fA-F]{8}\Z/], Pattern[/\A(0x)?[0-9a-fA-F]{16}\Z/], Pattern[/\A(0x)?[0-9a-fA-F]{40}\Z/]]',
|
151
|
+
behaviour: :namevar,
|
152
|
+
desc: 'The ID of the key you want to manage.',
|
153
|
+
},
|
154
|
+
# ...
|
155
|
+
created: {
|
156
|
+
type: 'String',
|
157
|
+
behaviour: :read_only,
|
158
|
+
desc: 'Date the key was created, in ISO format.',
|
159
|
+
},
|
160
|
+
},
|
161
|
+
autorequires: {
|
162
|
+
file: '$source', # will evaluate to the value of the `source` attribute
|
163
|
+
package: 'apt',
|
164
|
+
},
|
165
|
+
)
|
126
166
|
SOURCE
|
127
167
|
end
|
128
168
|
|