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.
Files changed (42) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +21 -0
  3. data/Gemfile +4 -2
  4. data/README.md +53 -10
  5. data/codecov.yml +3 -0
  6. data/lib/puppet-strings.rb +30 -11
  7. data/lib/puppet-strings/json.rb +7 -0
  8. data/lib/puppet-strings/markdown.rb +35 -0
  9. data/lib/puppet-strings/markdown/base.rb +168 -0
  10. data/lib/puppet-strings/markdown/defined_type.rb +14 -0
  11. data/lib/puppet-strings/markdown/defined_types.rb +37 -0
  12. data/lib/puppet-strings/markdown/function.rb +52 -0
  13. data/lib/puppet-strings/markdown/functions.rb +38 -0
  14. data/lib/puppet-strings/markdown/puppet_class.rb +14 -0
  15. data/lib/puppet-strings/markdown/puppet_classes.rb +37 -0
  16. data/lib/puppet-strings/markdown/resource_type.rb +27 -0
  17. data/lib/puppet-strings/markdown/resource_types.rb +37 -0
  18. data/lib/puppet-strings/markdown/table_of_contents.rb +21 -0
  19. data/lib/puppet-strings/markdown/templates/classes_and_defines.erb +63 -0
  20. data/lib/puppet-strings/markdown/templates/function.erb +50 -0
  21. data/lib/puppet-strings/markdown/templates/resource_type.erb +114 -0
  22. data/lib/puppet-strings/markdown/templates/table_of_contents.erb +21 -0
  23. data/lib/puppet-strings/tasks/generate.rb +24 -5
  24. data/lib/puppet-strings/yard/code_objects/function.rb +3 -3
  25. data/lib/puppet-strings/yard/code_objects/type.rb +3 -1
  26. data/lib/puppet-strings/yard/handlers.rb +1 -0
  27. data/lib/puppet-strings/yard/handlers/puppet/function_handler.rb +1 -1
  28. data/lib/puppet-strings/yard/handlers/ruby/base.rb +1 -1
  29. data/lib/puppet-strings/yard/handlers/ruby/rsapi_handler.rb +141 -0
  30. data/lib/puppet/face/strings.rb +28 -7
  31. data/spec/acceptance/emit_json_options.rb +4 -4
  32. data/spec/acceptance/generate_markdown_spec.rb +49 -0
  33. data/spec/fixtures/unit/json/output.json +43 -0
  34. data/spec/fixtures/unit/markdown/output.md +383 -0
  35. data/spec/spec_helper.rb +19 -1
  36. data/spec/unit/puppet-strings/json_spec.rb +40 -0
  37. data/spec/unit/puppet-strings/markdown/base_spec.rb +146 -0
  38. data/spec/unit/puppet-strings/markdown_spec.rb +248 -0
  39. data/spec/unit/puppet-strings/yard/handlers/puppet/function_handler_spec.rb +16 -1
  40. data/spec/unit/puppet-strings/yard/handlers/ruby/provider_handler_spec.rb +1 -1
  41. data/spec/unit/puppet-strings/yard/handlers/ruby/rsapi_handler_spec.rb +213 -0
  42. 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
+
@@ -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