puppet-strings 2.4.0 → 2.5.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (69) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +30 -2
  3. data/lib/puppet-strings.rb +2 -2
  4. data/lib/puppet-strings/markdown.rb +1 -1
  5. data/lib/puppet-strings/markdown/base.rb +6 -0
  6. data/lib/puppet-strings/markdown/data_type.rb +16 -0
  7. data/lib/puppet-strings/markdown/resource_type.rb +19 -2
  8. data/lib/puppet-strings/markdown/templates/classes_and_defines.erb +4 -4
  9. data/lib/puppet-strings/markdown/templates/data_type.erb +11 -4
  10. data/lib/puppet-strings/markdown/templates/data_type_function.erb +67 -0
  11. data/lib/puppet-strings/markdown/templates/function.erb +2 -1
  12. data/lib/puppet-strings/markdown/templates/puppet_task.erb +1 -1
  13. data/lib/puppet-strings/markdown/templates/resource_type.erb +12 -12
  14. data/lib/puppet-strings/markdown/templates/table_of_contents.erb +6 -6
  15. data/lib/puppet-strings/version.rb +1 -1
  16. data/lib/puppet-strings/yard/code_objects/data_type.rb +26 -6
  17. data/lib/puppet-strings/yard/code_objects/type.rb +46 -5
  18. data/lib/puppet-strings/yard/handlers/ruby/data_type_handler.rb +190 -43
  19. data/lib/puppet-strings/yard/handlers/ruby/type_base.rb +6 -0
  20. data/lib/puppet-strings/yard/handlers/ruby/type_extras_handler.rb +1 -1
  21. data/lib/puppet-strings/yard/handlers/ruby/type_handler.rb +6 -0
  22. data/lib/puppet-strings/yard/templates/default/puppet_data_type/html/method_details_list.erb +6 -0
  23. data/lib/puppet-strings/yard/templates/default/puppet_data_type/html/setup.rb +9 -1
  24. data/lib/puppet-strings/yard/templates/default/puppet_type/html/setup.rb +3 -1
  25. metadata +4 -46
  26. data/CODEOWNERS +0 -1
  27. data/Gemfile +0 -53
  28. data/HISTORY.md +0 -218
  29. data/JSON.md +0 -832
  30. data/Rakefile +0 -160
  31. data/codecov.yml +0 -3
  32. data/misc/ANNOUNCEMENT_TEMPLATE.md +0 -40
  33. data/spec/acceptance/emit_json_options_spec.rb +0 -69
  34. data/spec/acceptance/generate_markdown_spec.rb +0 -47
  35. data/spec/acceptance/running_strings_generate_spec.rb +0 -88
  36. data/spec/fixtures/acceptance/modules/test/functions/add.pp +0 -9
  37. data/spec/fixtures/acceptance/modules/test/lib/puppet/functions/4x_function.rb +0 -5
  38. data/spec/fixtures/acceptance/modules/test/lib/puppet/parser/functions/function3x.rb +0 -2
  39. data/spec/fixtures/acceptance/modules/test/lib/puppet/provider/server/linux.rb +0 -9
  40. data/spec/fixtures/acceptance/modules/test/lib/puppet/type/database.rb +0 -15
  41. data/spec/fixtures/acceptance/modules/test/manifests/init.pp +0 -31
  42. data/spec/fixtures/acceptance/modules/test/manifests/triple_nested_classes.pp +0 -27
  43. data/spec/fixtures/acceptance/modules/test/metadata.json +0 -10
  44. data/spec/fixtures/acceptance/modules/test/types/elephant.pp +0 -2
  45. data/spec/fixtures/unit/markdown/output.md +0 -561
  46. data/spec/fixtures/unit/markdown/output_with_data_types.md +0 -606
  47. data/spec/fixtures/unit/markdown/output_with_plan.md +0 -595
  48. data/spec/spec_helper.rb +0 -49
  49. data/spec/spec_helper_acceptance.rb +0 -58
  50. data/spec/spec_helper_acceptance_local.rb +0 -10
  51. data/spec/unit/puppet-strings/describe_spec.rb +0 -141
  52. data/spec/unit/puppet-strings/json_spec.rb +0 -302
  53. data/spec/unit/puppet-strings/markdown/base_spec.rb +0 -146
  54. data/spec/unit/puppet-strings/markdown_spec.rb +0 -374
  55. data/spec/unit/puppet-strings/yard/code_objects/task_spec.rb +0 -92
  56. data/spec/unit/puppet-strings/yard/handlers/json/task_handler_spec.rb +0 -116
  57. data/spec/unit/puppet-strings/yard/handlers/puppet/class_handler_spec.rb +0 -217
  58. data/spec/unit/puppet-strings/yard/handlers/puppet/data_type_alias_handler_spec.rb +0 -65
  59. data/spec/unit/puppet-strings/yard/handlers/puppet/defined_type_handler_spec.rb +0 -231
  60. data/spec/unit/puppet-strings/yard/handlers/puppet/function_handler_spec.rb +0 -315
  61. data/spec/unit/puppet-strings/yard/handlers/ruby/data_type_handler_spec.rb +0 -309
  62. data/spec/unit/puppet-strings/yard/handlers/ruby/function_handler_spec.rb +0 -746
  63. data/spec/unit/puppet-strings/yard/handlers/ruby/provider_handler_spec.rb +0 -158
  64. data/spec/unit/puppet-strings/yard/handlers/ruby/rsapi_handler_spec.rb +0 -235
  65. data/spec/unit/puppet-strings/yard/handlers/ruby/type_handler_spec.rb +0 -311
  66. data/spec/unit/puppet-strings/yard/parsers/json/parser_spec.rb +0 -72
  67. data/spec/unit/puppet-strings/yard/parsers/json/task_statement_spec.rb +0 -56
  68. data/spec/unit/puppet-strings/yard/parsers/puppet/parser_spec.rb +0 -251
  69. data/spec/unit/puppet-strings/yard/util_spec.rb +0 -48
@@ -1,146 +0,0 @@
1
- require 'spec_helper'
2
-
3
- describe PuppetStrings::Markdown::Base do
4
- context 'basic class' do
5
- before :each do
6
- YARD::Parser::SourceParser.parse_string(<<-SOURCE, :puppet)
7
- # An overview
8
- # @api private
9
- # @summary A simple class.
10
- # @param param1 First param.
11
- # @param param2 Second param.
12
- # @param param3 Third param.
13
- class klass(Integer $param1, $param2, String $param3 = hi) inherits foo::bar {
14
- }
15
- SOURCE
16
- end
17
-
18
- let(:reg) { YARD::Registry.all(:puppet_class).sort_by!(&:name).map!(&:to_hash)[0] }
19
- let(:component) { PuppetStrings::Markdown::Base.new(reg, 'class') }
20
-
21
- describe '#name' do
22
- it 'returns the expected name' do
23
- expect(component.name).to eq 'klass'
24
- end
25
- end
26
-
27
- ['examples',
28
- 'see',
29
- 'since',
30
- 'return_val',
31
- 'return_type',].each do |method|
32
- describe "##{method}" do
33
- it 'returns nil' do
34
- expect(component.method(method.to_sym).call).to be_nil
35
- end
36
- end
37
-
38
- end
39
-
40
- describe '#private?' do
41
- it do
42
- expect(component.private?).to be true
43
- end
44
- end
45
-
46
- describe '#params' do
47
- it 'returns the expected params' do
48
- expect(component.params.size).to eq 3
49
- end
50
- end
51
-
52
- describe '#summary' do
53
- it 'returns the expected summary' do
54
- expect(component.summary).to eq 'A simple class.'
55
- end
56
- end
57
-
58
- describe '#toc_info' do
59
- let(:toc) { component.toc_info }
60
- it 'returns a hash' do
61
- expect(toc).to be_instance_of Hash
62
- end
63
- it 'prefers the summary for :desc' do
64
- expect(toc[:desc]).to eq 'A simple class.'
65
- end
66
- end
67
- end
68
- context 'less basic class' do
69
- before :each do
70
- YARD::Parser::SourceParser.parse_string(<<-SOURCE, :puppet)
71
- # An overview
72
- # It's a longer overview
73
- # Ya know?
74
- # @example A simple example.
75
- # class { 'klass::yeah':
76
- # param1 => 1,
77
- # }
78
- # @param param1 First param.
79
- # @param param2 Second param.
80
- # @param param3 Third param.
81
- class klass::yeah(
82
- Integer $param1,
83
- $param2,
84
- String $param3 = hi
85
- ) inherits foo::bar {
86
-
87
- }
88
- SOURCE
89
- end
90
-
91
- let(:reg) { YARD::Registry.all(:puppet_class).sort_by!(&:name).map!(&:to_hash)[0] }
92
- let(:component) { PuppetStrings::Markdown::Base.new(reg, 'class') }
93
-
94
- describe '#name' do
95
- it 'returns the expected name' do
96
- expect(component.name).to eq 'klass::yeah'
97
- end
98
- end
99
-
100
- ['summary',
101
- 'see',
102
- 'since',
103
- 'return_val',
104
- 'return_type'].each do |method|
105
- describe "##{method}" do
106
- it 'returns nil' do
107
- expect(component.method(method.to_sym).call).to be_nil
108
- end
109
- end
110
- end
111
-
112
- describe '#examples' do
113
- it 'should return one example' do
114
- expect(component.examples.size).to eq 1
115
- end
116
- end
117
-
118
- describe '#params' do
119
- it 'returns the expected params' do
120
- expect(component.params.size).to eq 3
121
- end
122
- end
123
-
124
- describe '#private?' do
125
- it do
126
- expect(component.private?).to be false
127
- end
128
- end
129
-
130
- describe '#toc_info' do
131
- let(:toc) { component.toc_info }
132
- it 'returns a hash' do
133
- expect(toc).to be_instance_of Hash
134
- end
135
- it 'uses overview for :desc in absence of summary' do
136
- expect(toc[:desc]).to eq 'An overview It\'s a longer overview Ya know?'
137
- end
138
- end
139
-
140
- describe '#link' do
141
- it 'returns a valid link' do
142
- expect(component.link).to eq 'klassyeah'
143
- end
144
- end
145
- end
146
- end
@@ -1,374 +0,0 @@
1
- require 'spec_helper'
2
- require 'puppet-strings/markdown'
3
- require 'puppet-strings/markdown/table_of_contents'
4
- require 'tempfile'
5
-
6
- describe PuppetStrings::Markdown do
7
- def parse_shared_content
8
- # Populate the YARD registry with both Puppet and Ruby source
9
- YARD::Parser::SourceParser.parse_string(<<-SOURCE, :puppet)
10
- # An overview for a simple class.
11
- # @summary A simple class.
12
- # @todo Do a thing
13
- # @note some note
14
- # @since 1.0.0
15
- # @see www.puppet.com
16
- # @example This is an example
17
- # class { 'klass':
18
- # param1 => 1,
19
- # param3 => 'foo',
20
- # }
21
- # @example This is another example
22
- # class { 'klass':
23
- # param1 => 1,
24
- # param3 => 'foo',
25
- # }
26
- # @raise SomeError
27
- # @param param1 First param.
28
- # @param param2 Second param.
29
- # @option param2 [String] :opt1 something about opt1
30
- # @option param2 [Hash] :opt2 a hash of stuff
31
- # @param param3 Third param.
32
- # @param param4 Fourth param.
33
- # @enum param4 :one One option
34
- # @enum param4 :two Second option
35
- #
36
- class klass (
37
- Integer $param1 = 1,
38
- $param2 = undef,
39
- String $param3 = 'hi',
40
- Enum['one', 'two'] $param4 = 'two',
41
- ) inherits foo::bar {
42
- }
43
-
44
- # Overview for class noparams
45
- # @api private
46
- class noparams () {}
47
-
48
- # An overview for a simple defined type.
49
- # @summary A simple defined type.
50
- # @since 1.1.0
51
- # @see www.puppet.com
52
- # @example Here's an example of this type:
53
- # klass::dt { 'foo':
54
- # param1 => 33,
55
- # param4 => false,
56
- # }
57
- # @return shouldn't return squat
58
- # @raise SomeError
59
- # @param param1 First param.
60
- # @param param2 Second param.
61
- # @option param2 [String] :opt1 something about opt1
62
- # @option param2 [Hash] :opt2 a hash of stuff
63
- # @param param3 Third param.
64
- # @param param4 Fourth param.
65
- # @param param5 Fifth param.
66
- # @enum param5 :a Option A
67
- # @enum param5 :b Option B
68
- define klass::dt (
69
- Integer $param1 = 44,
70
- $param2,
71
- String $param3 = 'hi',
72
- Boolean $param4 = true,
73
- Enum['a', 'b'] $param5 = 'a'
74
- ) {
75
- }
76
- SOURCE
77
-
78
- YARD::Parser::SourceParser.parse_string(<<-SOURCE, :json)
79
- {
80
- "description": "Allows you to backup your database to local file.",
81
- "input_method": "stdin",
82
- "parameters": {
83
- "database": {
84
- "description": "Database to connect to",
85
- "type": "Optional[String[1]]"
86
- },
87
- "user": {
88
- "description": "The user",
89
- "type": "Optional[String[1]]"
90
- },
91
- "password": {
92
- "description": "The password",
93
- "type": "Optional[String[1]]"
94
- },
95
- "sql": {
96
- "description": "Path to file you want backup to",
97
- "type": "String[1]"
98
- }
99
- }
100
- }
101
- SOURCE
102
-
103
- YARD::Parser::SourceParser.parse_string(<<-SOURCE, :puppet)
104
- # A simple Puppet function.
105
- # @param param1 First param.
106
- # @param param2 Second param.
107
- # @param param3 Third param.
108
- # @option param3 [Array] :param3opt Something about this option
109
- # @param param4 Fourth param.
110
- # @enum param4 :yes Yes option.
111
- # @enum param4 :no No option.
112
- # @raise SomeError this is some error
113
- # @return [Undef] Returns nothing.
114
- # @example Test
115
- # $result = func(1, 2)
116
- function func(Integer $param1, $param2, String $param3 = hi, Enum['yes', 'no'] $param4 = 'yes') {
117
- }
118
- SOURCE
119
-
120
- YARD::Parser::SourceParser.parse_string(<<-SOURCE, :ruby)
121
- # An example 4.x function.
122
- #
123
- # @example Calling the function
124
- # $result = func4x(1, 'foo')
125
- #
126
- # @example Calling the function with all args
127
- # $result = func4x(1, 'foo', ['bar'])
128
- Puppet::Functions.create_function(:func4x) do
129
- # An overview for the first overload.
130
- # @raise SomeError this is some error
131
- # @param param1 The first parameter.
132
- # @param param2 The second parameter.
133
- # @option param2 [String] :option an option
134
- # @option param2 [String] :option2 another option
135
- # @param param3 The third parameter.
136
- # @param param4 The fourth parameter.
137
- # @enum param4 :one Option one.
138
- # @enum param4 :two Option two.
139
- # @return Returns nothing.
140
- # @example Calling the function foo
141
- # $result = func4x(1, 'foooo')
142
- #
143
- dispatch :foo do
144
- param 'Integer', :param1
145
- param 'Any', :param2
146
- optional_param 'Array[String]', :param3
147
- optional_param 'Enum[one, two]', :param4
148
- return_type 'Undef'
149
- end
150
-
151
- # An overview for the second overload.
152
- # @param param The first parameter.
153
- # @param block The block parameter.
154
- # @return Returns a string.
155
- # @example Calling the function bar
156
- # $result = func4x(1, 'bar', ['foo'])
157
- dispatch :other do
158
- param 'Boolean', :param
159
- block_param
160
- return_type 'String'
161
- end
162
- end
163
-
164
- # An example 4.x function with only one signature.
165
- Puppet::Functions.create_function(:func4x_1) do
166
- # @param param1 The first parameter.
167
- # @return [Undef] Returns nothing.
168
- dispatch :foobarbaz do
169
- param 'Integer', :param1
170
- end
171
- end
172
-
173
- # An example 3.x function
174
- Puppet::Parser::Functions.newfunction(:func3x, doc: <<-DOC
175
- Documentation for an example 3.x function.
176
- @param param1 [String] The first parameter.
177
- @param param2 [Integer] The second parameter.
178
- @return [Undef]
179
- @example Calling the function.
180
- func3x('hi', 10)
181
- DOC
182
- ) do |*args|
183
- #...
184
- end
185
-
186
- Puppet::Type.type(:database).provide :linux do
187
- desc 'An example provider on Linux.'
188
- confine kernel: 'Linux'
189
- confine osfamily: 'RedHat'
190
- defaultfor :kernel => 'Linux'
191
- defaultfor :osfamily => 'RedHat', :operatingsystemmajrelease => '7'
192
- has_feature :implements_some_feature
193
- has_feature :some_other_feature
194
- commands foo: '/usr/bin/foo'
195
- end
196
-
197
- Puppet::Type.newtype(:database) do
198
- desc <<-DESC
199
- An example database server type.
200
- @option opts :foo bar
201
- @enum ensure :up Upstate
202
- @enum ensure :down Downstate
203
- @raise SomeError
204
- @example here's an example
205
- database { 'foo':
206
- address => 'qux.baz.bar',
207
- }
208
- DESC
209
- feature :encryption, 'The provider supports encryption.', methods: [:encrypt]
210
- ensurable do
211
- desc 'What state the database should be in.'
212
- defaultvalues
213
- aliasvalue(:up, :present)
214
- aliasvalue(:down, :absent)
215
- defaultto :up
216
- end
217
-
218
- newparam(:address) do
219
- isnamevar
220
- desc 'The database server name.'
221
- end
222
-
223
- newparam(:encryption_key, required_features: :encryption) do
224
- desc 'The encryption key to use.'
225
- end
226
-
227
- newparam(:encrypt, :parent => Puppet::Parameter::Boolean) do
228
- desc 'Whether or not to encrypt the database.'
229
- defaultto false
230
- end
231
-
232
- newproperty(:file) do
233
- desc 'The database file to use.'
234
- end
235
-
236
- newproperty(:log_level) do
237
- desc 'The log level to use.'
238
- newvalue(:debug)
239
- newvalue(:warn)
240
- newvalue(:error)
241
- defaultto 'warn'
242
- end
243
- end
244
-
245
- Puppet::ResourceApi.register_type(
246
- name: 'apt_key',
247
- docs: <<-EOS,
248
- @summary Example resource type using the new API.
249
- @raise SomeError
250
- This type provides Puppet with the capabilities to manage GPG keys needed
251
- by apt to perform package validation. Apt has it's own GPG keyring that can
252
- be manipulated through the `apt-key` command.
253
- @example here's an example
254
- apt_key { '6F6B15509CF8E59E6E469F327F438280EF8D349F':
255
- source => 'http://apt.puppetlabs.com/pubkey.gpg'
256
- }
257
-
258
- **Autorequires**:
259
- If Puppet is given the location of a key file which looks like an absolute
260
- path this type will autorequire that file.
261
- EOS
262
- attributes: {
263
- ensure: {
264
- type: 'Enum[present, absent]',
265
- desc: 'Whether this apt key should be present or absent on the target system.'
266
- },
267
- id: {
268
- 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/]]',
269
- behaviour: :namevar,
270
- desc: 'The ID of the key you want to manage.',
271
- },
272
- # ...
273
- created: {
274
- type: 'String',
275
- behaviour: :read_only,
276
- desc: 'Date the key was created, in ISO format.',
277
- },
278
- },
279
- autorequires: {
280
- file: '$source', # will evaluate to the value of the `source` attribute
281
- package: 'apt',
282
- },
283
- )
284
- SOURCE
285
- end
286
-
287
- def parse_plan_content
288
- YARD::Parser::SourceParser.parse_string(<<-SOURCE, :puppet)
289
- # A simple plan.
290
- # @param param1 First param.
291
- # @param param2 Second param.
292
- # @param param3 Third param.
293
- plan plann(String $param1, $param2, Integer $param3 = 1) {
294
- }
295
- SOURCE
296
- end
297
-
298
- def parse_data_type_content
299
- YARD::Parser::SourceParser.parse_string(<<-SOURCE, :ruby)
300
- # An example Puppet Data Type in Ruby.
301
- #
302
- # @param param1 A variant parameter.
303
- # @param param2 Optional String parameter.
304
- Puppet::DataTypes.create_type('UnitDataType') do
305
- interface <<-PUPPET
306
- attributes => {
307
- param1 => Variant[Numeric, String[1,2]],
308
- param2 => { type => Optional[String[1]], value => "param2" }
309
- }
310
- PUPPET
311
- end
312
- SOURCE
313
-
314
- YARD::Parser::SourceParser.parse_string(<<-SOURCE, :puppet)
315
- # Documentation for Amodule::SimpleAlias
316
- type Amodule::SimpleAlias = Variant[Numeric,String[1,20]]
317
-
318
- # Documentation for Amodule::ComplexAlias
319
- type Amodule::ComplexAlias = Struct[{
320
- value_type => Optional[ValueType],
321
- merge => Optional[MergeType]
322
- }]
323
- SOURCE
324
- end
325
- let(:baseline_path) { File.join(File.dirname(__FILE__), "../../fixtures/unit/markdown/#{filename}") }
326
- let(:baseline) { File.read(baseline_path) }
327
-
328
- describe 'rendering markdown to a file' do
329
- before(:each) do
330
- parse_shared_content
331
- end
332
-
333
- context 'with common Puppet and ruby content' do
334
- let(:filename) { 'output.md' }
335
-
336
- it 'should output the expected markdown content' do
337
- Tempfile.open('md') do |file|
338
- PuppetStrings::Markdown.render(file.path)
339
- expect(File.read(file.path)).to eq(baseline)
340
- end
341
- end
342
- end
343
-
344
- describe 'with Puppet Plans', :if => TEST_PUPPET_PLANS do
345
- let(:filename) { 'output_with_plan.md' }
346
-
347
- before(:each) do
348
- parse_plan_content
349
- end
350
-
351
- it 'should output the expected markdown content' do
352
- Tempfile.open('md') do |file|
353
- PuppetStrings::Markdown.render(file.path)
354
- expect(File.read(file.path)).to eq(baseline)
355
- end
356
- end
357
- end
358
-
359
- describe 'with Puppet Data Types', :if => TEST_PUPPET_DATATYPES do
360
- let(:filename) { 'output_with_data_types.md' }
361
-
362
- before(:each) do
363
- parse_data_type_content
364
- end
365
-
366
- it 'should output the expected markdown content' do
367
- Tempfile.open('md') do |file|
368
- PuppetStrings::Markdown.render(file.path)
369
- expect(File.read(file.path)).to eq(baseline)
370
- end
371
- end
372
- end
373
- end
374
- end