puppet-strings 2.1.0 → 2.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 (45) hide show
  1. checksums.yaml +5 -5
  2. data/CHANGELOG.md +18 -3
  3. data/Gemfile +3 -2
  4. data/Rakefile +5 -0
  5. data/lib/puppet-strings.rb +10 -1
  6. data/lib/puppet-strings/describe.rb +68 -0
  7. data/lib/puppet-strings/json.rb +0 -38
  8. data/lib/puppet-strings/markdown/base.rb +18 -16
  9. data/lib/puppet-strings/markdown/templates/function.erb +26 -0
  10. data/lib/puppet-strings/markdown/templates/resource_type.erb +4 -0
  11. data/lib/puppet-strings/tasks/generate.rb +7 -1
  12. data/lib/puppet-strings/version.rb +1 -1
  13. data/lib/puppet-strings/yard/code_objects/class.rb +1 -1
  14. data/lib/puppet-strings/yard/code_objects/defined_type.rb +1 -1
  15. data/lib/puppet-strings/yard/code_objects/function.rb +3 -3
  16. data/lib/puppet-strings/yard/code_objects/plan.rb +1 -1
  17. data/lib/puppet-strings/yard/code_objects/provider.rb +1 -1
  18. data/lib/puppet-strings/yard/code_objects/type.rb +3 -2
  19. data/lib/puppet-strings/yard/handlers.rb +1 -0
  20. data/lib/puppet-strings/yard/handlers/ruby/base.rb +11 -0
  21. data/lib/puppet-strings/yard/handlers/ruby/function_handler.rb +1 -9
  22. data/lib/puppet-strings/yard/handlers/ruby/provider_handler.rb +1 -9
  23. data/lib/puppet-strings/yard/handlers/ruby/rsapi_handler.rb +1 -1
  24. data/lib/puppet-strings/yard/handlers/ruby/type_base.rb +130 -0
  25. data/lib/puppet-strings/yard/handlers/ruby/type_extras_handler.rb +56 -0
  26. data/lib/puppet-strings/yard/handlers/ruby/type_handler.rb +3 -115
  27. data/lib/puppet-strings/yard/parsers/json/parser.rb +3 -1
  28. data/lib/puppet-strings/yard/tags/overload_tag.rb +1 -1
  29. data/lib/puppet-strings/yard/util.rb +48 -0
  30. data/lib/puppet/face/strings.rb +66 -1
  31. data/spec/fixtures/unit/markdown/output.md +64 -0
  32. data/spec/fixtures/unit/markdown/output_with_plan.md +64 -0
  33. data/spec/spec_helper.rb +1 -0
  34. data/spec/unit/puppet-strings/describe_spec.rb +141 -0
  35. data/spec/unit/puppet-strings/json_spec.rb +65 -11
  36. data/spec/unit/puppet-strings/markdown_spec.rb +13 -0
  37. data/spec/unit/puppet-strings/yard/handlers/json/task_handler_spec.rb +4 -12
  38. data/spec/unit/puppet-strings/yard/handlers/ruby/function_handler_spec.rb +1 -1
  39. data/spec/unit/puppet-strings/yard/handlers/ruby/rsapi_handler_spec.rb +21 -0
  40. data/spec/unit/puppet-strings/yard/handlers/ruby/type_handler_spec.rb +26 -0
  41. data/spec/unit/puppet-strings/yard/parsers/json/parser_spec.rb +5 -3
  42. metadata +7 -6
  43. data/spec/fixtures/unit/json/output.json +0 -660
  44. data/spec/fixtures/unit/json/output_with_plan.json +0 -697
  45. data/spec/fixtures/unit/json/output_without_puppet_function.json +0 -480
data/spec/fixtures/unit/json/output_with_plan.json DELETED
@@ -1,697 +0,0 @@
1
- {
2
- "puppet_classes": [
3
- {
4
- "name": "klass",
5
- "file": "(stdin)",
6
- "line": 7,
7
- "inherits": "foo::bar",
8
- "docstring": {
9
- "text": "A simple class.",
10
- "tags": [
11
- {
12
- "tag_name": "todo",
13
- "text": "Do a thing"
14
- },
15
- {
16
- "tag_name": "note",
17
- "text": "Some note"
18
- },
19
- {
20
- "tag_name": "param",
21
- "text": "First param.",
22
- "types": [
23
- "Integer"
24
- ],
25
- "name": "param1"
26
- },
27
- {
28
- "tag_name": "param",
29
- "text": "Second param.",
30
- "types": [
31
- "Any"
32
- ],
33
- "name": "param2"
34
- },
35
- {
36
- "tag_name": "param",
37
- "text": "Third param.",
38
- "types": [
39
- "String"
40
- ],
41
- "name": "param3"
42
- }
43
- ]
44
- },
45
- "defaults": {
46
- "param3": "hi"
47
- },
48
- "source": "class klass(Integer $param1, $param2, String $param3 = hi) inherits foo::bar {\n}"
49
- }
50
- ],
51
- "defined_types": [
52
- {
53
- "name": "dt",
54
- "file": "(stdin)",
55
- "line": 14,
56
- "docstring": {
57
- "text": "A simple defined type.",
58
- "tags": [
59
- {
60
- "tag_name": "param",
61
- "text": "First param.",
62
- "types": [
63
- "Integer"
64
- ],
65
- "name": "param1"
66
- },
67
- {
68
- "tag_name": "param",
69
- "text": "Second param.",
70
- "types": [
71
- "Any"
72
- ],
73
- "name": "param2"
74
- },
75
- {
76
- "tag_name": "param",
77
- "text": "Third param.",
78
- "types": [
79
- "String"
80
- ],
81
- "name": "param3"
82
- }
83
- ]
84
- },
85
- "defaults": {
86
- "param3": "hi"
87
- },
88
- "source": "define dt(Integer $param1, $param2, String $param3 = hi) {\n}"
89
- }
90
- ],
91
- "resource_types": [
92
- {
93
- "name": "apt_key",
94
- "file": "(stdin)",
95
- "line": 92,
96
- "docstring": {
97
- "text": "This type provides Puppet with the capabilities to manage GPG keys needed\nby apt to perform package validation. Apt has it's own GPG keyring that can\nbe manipulated through the `apt-key` command.\n**Autorequires**:\nIf Puppet is given the location of a key file which looks like an absolute\npath this type will autorequire that file.",
98
- "tags": [
99
- {
100
- "tag_name": "summary",
101
- "text": "Example resource type using the new API."
102
- },
103
- {
104
- "tag_name": "raise",
105
- "text": "SomeError"
106
- },
107
- {
108
- "tag_name": "example",
109
- "text": "apt_key { '6F6B15509CF8E59E6E469F327F438280EF8D349F':\n source => 'http://apt.puppetlabs.com/pubkey.gpg'\n}",
110
- "name": "here's an example"
111
- }
112
- ]
113
- },
114
- "properties": [
115
- {
116
- "name": "ensure",
117
- "description": "Whether this apt key should be present or absent on the target system.",
118
- "data_type": "Enum[present, absent]"
119
- },
120
- {
121
- "name": "created",
122
- "description": "Date the key was created, in ISO format.",
123
- "data_type": "String"
124
- }
125
- ],
126
- "parameters": [
127
- {
128
- "name": "id",
129
- "description": "The ID of the key you want to manage.",
130
- "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/]]",
131
- "isnamevar": true
132
- }
133
- ]
134
- },
135
- {
136
- "name": "database",
137
- "file": "(stdin)",
138
- "line": 54,
139
- "docstring": {
140
- "text": "An example database server resource type."
141
- },
142
- "properties": [
143
- {
144
- "name": "ensure",
145
- "description": "What state the database should be in.",
146
- "values": [
147
- "present",
148
- "absent",
149
- "up",
150
- "down"
151
- ],
152
- "aliases": {
153
- "up": "present",
154
- "down": "absent"
155
- },
156
- "default": "up"
157
- },
158
- {
159
- "name": "file",
160
- "description": "The database file to use."
161
- },
162
- {
163
- "name": "log_level",
164
- "description": "The log level to use.",
165
- "values": [
166
- "debug",
167
- "warn",
168
- "error"
169
- ],
170
- "default": "warn"
171
- }
172
- ],
173
- "parameters": [
174
- {
175
- "name": "address",
176
- "description": "The database server name.",
177
- "isnamevar": true
178
- },
179
- {
180
- "name": "encryption_key",
181
- "description": "The encryption key to use."
182
- },
183
- {
184
- "name": "encrypt",
185
- "description": "Whether or not to encrypt the database.",
186
- "values": [
187
- "true",
188
- "false",
189
- "yes",
190
- "no"
191
- ],
192
- "default": "false"
193
- }
194
- ],
195
- "features": [
196
- {
197
- "name": "encryption",
198
- "description": "The provider supports encryption."
199
- }
200
- ]
201
- }
202
- ],
203
- "providers": [
204
- {
205
- "name": "linux",
206
- "type_name": "database",
207
- "file": "(stdin)",
208
- "line": 43,
209
- "docstring": {
210
- "text": "An example provider on Linux."
211
- },
212
- "confines": {
213
- "kernel": "Linux",
214
- "osfamily": "RedHat"
215
- },
216
- "features": [
217
- "implements_some_feature",
218
- "some_other_feature"
219
- ],
220
- "defaults": [
221
- [
222
- [
223
- "kernel",
224
- "Linux"
225
- ]
226
- ],
227
- [
228
- [
229
- "osfamily",
230
- "RedHat"
231
- ],
232
- [
233
- "operatingsystemmajrelease",
234
- "7"
235
- ]
236
- ]
237
- ],
238
- "commands": {
239
- "foo": "/usr/bin/foo"
240
- }
241
- }
242
- ],
243
- "puppet_functions": [
244
- {
245
- "name": "func",
246
- "file": "(stdin)",
247
- "line": 6,
248
- "type": "puppet",
249
- "signatures": [
250
- {
251
- "signature": "func(Integer $param1, Any $param2, String $param3 = hi)",
252
- "docstring": {
253
- "text": "A simple function.",
254
- "tags": [
255
- {
256
- "tag_name": "param",
257
- "text": "First param.",
258
- "types": [
259
- "Integer"
260
- ],
261
- "name": "param1"
262
- },
263
- {
264
- "tag_name": "param",
265
- "text": "Second param.",
266
- "types": [
267
- "Any"
268
- ],
269
- "name": "param2"
270
- },
271
- {
272
- "tag_name": "param",
273
- "text": "Third param.",
274
- "types": [
275
- "String"
276
- ],
277
- "name": "param3"
278
- },
279
- {
280
- "tag_name": "return",
281
- "text": "Returns nothing.",
282
- "types": [
283
- "Undef"
284
- ]
285
- }
286
- ]
287
- }
288
- }
289
- ],
290
- "docstring": {
291
- "text": "A simple function.",
292
- "tags": [
293
- {
294
- "tag_name": "param",
295
- "text": "First param.",
296
- "types": [
297
- "Integer"
298
- ],
299
- "name": "param1"
300
- },
301
- {
302
- "tag_name": "param",
303
- "text": "Second param.",
304
- "types": [
305
- "Any"
306
- ],
307
- "name": "param2"
308
- },
309
- {
310
- "tag_name": "param",
311
- "text": "Third param.",
312
- "types": [
313
- "String"
314
- ],
315
- "name": "param3"
316
- },
317
- {
318
- "tag_name": "return",
319
- "text": "Returns nothing.",
320
- "types": [
321
- "Undef"
322
- ]
323
- }
324
- ]
325
- },
326
- "defaults": {
327
- "param3": "hi"
328
- },
329
- "source": "function func(Integer $param1, $param2, String $param3 = hi) {\n}"
330
- },
331
- {
332
- "name": "func3x",
333
- "file": "(stdin)",
334
- "line": 1,
335
- "type": "ruby3x",
336
- "signatures": [
337
- {
338
- "signature": "func3x(String $first, Any $second)",
339
- "docstring": {
340
- "text": "An example 3.x function.",
341
- "tags": [
342
- {
343
- "tag_name": "param",
344
- "text": "The first parameter.",
345
- "types": [
346
- "String"
347
- ],
348
- "name": "first"
349
- },
350
- {
351
- "tag_name": "param",
352
- "text": "The second parameter.",
353
- "types": [
354
- "Any"
355
- ],
356
- "name": "second"
357
- },
358
- {
359
- "tag_name": "return",
360
- "text": "Returns nothing.",
361
- "types": [
362
- "Undef"
363
- ]
364
- }
365
- ]
366
- }
367
- }
368
- ],
369
- "docstring": {
370
- "text": "An example 3.x function.",
371
- "tags": [
372
- {
373
- "tag_name": "param",
374
- "text": "The first parameter.",
375
- "types": [
376
- "String"
377
- ],
378
- "name": "first"
379
- },
380
- {
381
- "tag_name": "param",
382
- "text": "The second parameter.",
383
- "types": [
384
- "Any"
385
- ],
386
- "name": "second"
387
- },
388
- {
389
- "tag_name": "return",
390
- "text": "Returns nothing.",
391
- "types": [
392
- "Undef"
393
- ]
394
- }
395
- ]
396
- },
397
- "source": "Puppet::Parser::Functions.newfunction(:func3x, doc: <<-DOC\nAn example 3.x function.\n@param [String] first The first parameter.\n@param second The second parameter.\n@return [Undef] Returns nothing.\nDOC\n) do |*args|\nend"
398
- },
399
- {
400
- "name": "func4x",
401
- "file": "(stdin)",
402
- "line": 11,
403
- "type": "ruby4x",
404
- "signatures": [
405
- {
406
- "signature": "func4x(Integer $param1, Any $param2, Optional[Array[String]] $param3)",
407
- "docstring": {
408
- "text": "The first overload.",
409
- "tags": [
410
- {
411
- "tag_name": "param",
412
- "text": "The first parameter.",
413
- "types": [
414
- "Integer"
415
- ],
416
- "name": "param1"
417
- },
418
- {
419
- "tag_name": "param",
420
- "text": "The second parameter.",
421
- "types": [
422
- "Any"
423
- ],
424
- "name": "param2"
425
- },
426
- {
427
- "tag_name": "param",
428
- "text": "The third parameter.",
429
- "types": [
430
- "Optional[Array[String]]"
431
- ],
432
- "name": "param3"
433
- },
434
- {
435
- "tag_name": "return",
436
- "text": "Returns nothing.",
437
- "types": [
438
- "Undef"
439
- ]
440
- }
441
- ]
442
- }
443
- },
444
- {
445
- "signature": "func4x(Boolean $param, Callable &$block)",
446
- "docstring": {
447
- "text": "",
448
- "tags": [
449
- {
450
- "tag_name": "param",
451
- "text": "The first parameter.",
452
- "types": [
453
- "Boolean"
454
- ],
455
- "name": "param"
456
- },
457
- {
458
- "tag_name": "param",
459
- "text": "The block parameter.",
460
- "types": [
461
- "Callable"
462
- ],
463
- "name": "&block"
464
- },
465
- {
466
- "tag_name": "return",
467
- "text": "Returns a string.",
468
- "types": [
469
- "String"
470
- ]
471
- }
472
- ]
473
- }
474
- }
475
- ],
476
- "docstring": {
477
- "text": "An example 4.x function.",
478
- "tags": [
479
- {
480
- "tag_name": "overload",
481
- "signature": "func4x(Integer $param1, Any $param2, Optional[Array[String]] $param3)",
482
- "docstring": {
483
- "text": "The first overload.",
484
- "tags": [
485
- {
486
- "tag_name": "param",
487
- "text": "The first parameter.",
488
- "types": [
489
- "Integer"
490
- ],
491
- "name": "param1"
492
- },
493
- {
494
- "tag_name": "param",
495
- "text": "The second parameter.",
496
- "types": [
497
- "Any"
498
- ],
499
- "name": "param2"
500
- },
501
- {
502
- "tag_name": "param",
503
- "text": "The third parameter.",
504
- "types": [
505
- "Optional[Array[String]]"
506
- ],
507
- "name": "param3"
508
- },
509
- {
510
- "tag_name": "return",
511
- "text": "Returns nothing.",
512
- "types": [
513
- "Undef"
514
- ]
515
- }
516
- ]
517
- },
518
- "name": "func4x"
519
- },
520
- {
521
- "tag_name": "overload",
522
- "signature": "func4x(Boolean $param, Callable &$block)",
523
- "docstring": {
524
- "text": "",
525
- "tags": [
526
- {
527
- "tag_name": "param",
528
- "text": "The first parameter.",
529
- "types": [
530
- "Boolean"
531
- ],
532
- "name": "param"
533
- },
534
- {
535
- "tag_name": "param",
536
- "text": "The block parameter.",
537
- "types": [
538
- "Callable"
539
- ],
540
- "name": "&block"
541
- },
542
- {
543
- "tag_name": "return",
544
- "text": "Returns a string.",
545
- "types": [
546
- "String"
547
- ]
548
- }
549
- ]
550
- },
551
- "name": "func4x"
552
- }
553
- ]
554
- },
555
- "source": "Puppet::Functions.create_function(:func4x) do\n # The first overload.\n # @param param1 The first parameter.\n # @param param2 The second parameter.\n # @param param3 The third parameter.\n # @return Returns nothing.\n dispatch :foo do\n param 'Integer', :param1\n param 'Any', :param2\n optional_param 'Array[String]', :param3\n return_type 'Undef'\n end\n\n # @param param The first parameter.\n # @param block The block parameter.\n # @return Returns a string.\n dispatch :other do\n param 'Boolean', :param\n block_param\n return_type 'String'\n end\nend"
556
- },
557
- {
558
- "name": "func4x_1",
559
- "file": "(stdin)",
560
- "line": 35,
561
- "type": "ruby4x",
562
- "signatures": [
563
- {
564
- "signature": "func4x_1(Integer $param1)",
565
- "docstring": {
566
- "text": "An example 4.x function with only one signature.",
567
- "tags": [
568
- {
569
- "tag_name": "param",
570
- "text": "The first parameter.",
571
- "types": [
572
- "Integer"
573
- ],
574
- "name": "param1"
575
- },
576
- {
577
- "tag_name": "return",
578
- "text": "Returns nothing.",
579
- "types": [
580
- "Undef"
581
- ]
582
- }
583
- ]
584
- }
585
- }
586
- ],
587
- "docstring": {
588
- "text": "An example 4.x function with only one signature.",
589
- "tags": [
590
- {
591
- "tag_name": "param",
592
- "text": "The first parameter.",
593
- "types": [
594
- "Integer"
595
- ],
596
- "name": "param1"
597
- },
598
- {
599
- "tag_name": "return",
600
- "text": "Returns nothing.",
601
- "types": [
602
- "Undef"
603
- ]
604
- }
605
- ]
606
- },
607
- "source": "Puppet::Functions.create_function(:func4x_1) do\n # @param param1 The first parameter.\n # @return [Undef] Returns nothing.\n dispatch :foobarbaz do\n param 'Integer', :param1\n end\nend"
608
- }
609
- ],
610
- "puppet_tasks": [
611
- {
612
- "name": "(stdin)",
613
- "file": "(stdin)",
614
- "line": 0,
615
- "docstring": {
616
- "text": "Allows you to backup your database to local file.",
617
- "tags": [
618
- {
619
- "name": "database",
620
- "tag_name": "param",
621
- "text": "Database to connect to",
622
- "types": [
623
- "Optional[String[1]]"
624
- ]
625
- },
626
- {
627
- "name": "user",
628
- "tag_name": "param",
629
- "text": "The user",
630
- "types": [
631
- "Optional[String[1]]"
632
- ]
633
- },
634
- {
635
- "name": "password",
636
- "tag_name": "param",
637
- "text": "The password",
638
- "types": [
639
- "Optional[String[1]]"
640
- ]
641
- },
642
- {
643
- "name": "sql",
644
- "tag_name": "param",
645
- "text": "Path to file you want backup to",
646
- "types": [
647
- "String[1]"
648
- ]
649
- }
650
- ]
651
- },
652
- "source": "{\n \"description\": \"Allows you to backup your database to local file.\",\n \"input_method\": \"stdin\",\n \"parameters\": {\n \"database\": {\n \"description\": \"Database to connect to\",\n \"type\": \"Optional[String[1]]\"\n },\n \"user\": {\n \"description\": \"The user\",\n \"type\": \"Optional[String[1]]\"\n },\n \"password\": {\n \"description\": \"The password\",\n \"type\": \"Optional[String[1]]\"\n },\n \"sql\": {\n \"description\": \"Path to file you want backup to\",\n \"type\": \"String[1]\"\n }\n }\n}\n",
653
- "supports_noop": false,
654
- "input_method": "stdin"
655
- }
656
- ],
657
- "puppet_plans": [
658
- {
659
- "name": "plann",
660
- "file": "(stdin)",
661
- "line": 5,
662
- "docstring": {
663
- "text": "A simple plan.",
664
- "tags": [
665
- {
666
- "tag_name": "param",
667
- "text": "First param.",
668
- "types": [
669
- "String"
670
- ],
671
- "name": "param1"
672
- },
673
- {
674
- "tag_name": "param",
675
- "text": "Second param.",
676
- "types": [
677
- "Any"
678
- ],
679
- "name": "param2"
680
- },
681
- {
682
- "tag_name": "param",
683
- "text": "Third param.",
684
- "types": [
685
- "Integer"
686
- ],
687
- "name": "param3"
688
- }
689
- ]
690
- },
691
- "defaults": {
692
- "param3": "1"
693
- },
694
- "source": "plan plann(String $param1, $param2, Integer $param3 = 1) {\n}"
695
- }
696
- ]
697
- }