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
data/Rakefile DELETED
@@ -1,160 +0,0 @@
1
- if Bundler.rubygems.find_name('puppet_litmus').any?
2
- require 'puppet_litmus/rake_tasks'
3
-
4
- # This is a _really_ horrible monkey-patch to fix up https://github.com/puppetlabs/bolt/issues/1614
5
- # Based on resolution https://github.com/puppetlabs/bolt/pull/1620
6
- # This can be removed once this is fixed, released into Bolt and into Litmus
7
- require 'bolt_spec/run'
8
- module BoltSpec
9
- module Run
10
- class BoltRunner
11
- class << self
12
- alias_method :original_with_runner, :with_runner
13
- end
14
-
15
- def self.with_runner(config_data, inventory_data)
16
- original_with_runner(deep_duplicate_object(config_data), deep_duplicate_object(inventory_data)) { |runner| yield runner }
17
- end
18
-
19
- # From https://github.com/puppetlabs/pdk/blob/master/lib/pdk/util.rb
20
- # Workaround for https://github.com/puppetlabs/bolt/issues/1614
21
- def self.deep_duplicate_object(object)
22
- if object.is_a?(Array)
23
- object.map { |item| deep_duplicate_object(item) }
24
- elsif object.is_a?(Hash)
25
- hash = object.dup
26
- hash.each_pair { |key, value| hash[key] = deep_duplicate_object(value) }
27
- hash
28
- else
29
- object
30
- end
31
- end
32
- end
33
- end
34
- end
35
- end
36
-
37
- require 'puppetlabs_spec_helper/tasks/fixtures'
38
- require 'bundler/gem_tasks'
39
- require 'puppet-lint/tasks/puppet-lint'
40
-
41
- require 'rspec/core/rake_task'
42
- RSpec::Core::RakeTask.new(:spec) do |t|
43
- t.exclude_pattern = "spec/acceptance/**/*.rb"
44
- end
45
-
46
- # Add our own tasks
47
- require 'puppet-strings/tasks'
48
-
49
- PuppetLint.configuration.send('disable_80chars')
50
- PuppetLint.configuration.ignore_paths = %w(acceptance/**/*.pp spec/**/*.pp pkg/**/*.pp)
51
-
52
- desc 'Validate Ruby source files and ERB templates.'
53
- task :validate do
54
- Dir['spec/**/*.rb','lib/**/*.rb'].each do |ruby_file|
55
- sh "ruby -c #{ruby_file}" unless ruby_file =~ /spec\/fixtures/
56
- end
57
- Dir['lib/puppet-strings/yard/templates/**/*.erb'].each do |template|
58
- sh "erb -P -x -T '-' #{template} | ruby -c"
59
- end
60
- end
61
-
62
- namespace :litmus do
63
- def install_remote_gem(gem_name, target_nodes, inventory_hash)
64
- # TODO: Currently this is Linux only
65
- install_command = "/opt/puppetlabs/puppet/bin/gem install #{gem_name}"
66
- result = run_command(install_command, target_nodes, config: nil, inventory: inventory_hash)
67
- if result.is_a?(Array)
68
- result.each do |node|
69
- puts "#{node['node']} failed #{node['result']}" if node['status'] != 'success'
70
- end
71
- else
72
- raise "Failed trying to run '#{install_command}' against inventory."
73
- end
74
- end
75
-
76
- # Install the gem under test and required fixture on a collection of nodes
77
- #
78
- # @param :target_node_name [Array] nodes on which to install a puppet module for testing.
79
- desc 'install_gems - build and install module fixtures'
80
- task :install_gems, [:target_node_name] do |_task, args|
81
- inventory_hash = inventory_hash_from_inventory_file
82
- target_nodes = find_targets(inventory_hash, args[:target_node_name])
83
- if target_nodes.empty?
84
- puts 'No targets found'
85
- exit 0
86
- end
87
- require 'bolt_spec/run'
88
- include BoltSpec::Run
89
-
90
- # Build the gem
91
- `gem build puppet-strings.gemspec --quiet`
92
- result = $CHILD_STATUS
93
- raise "Unable to build the puppet-strings gem. Returned exit code #{result.exitstatus}" unless result.exitstatus.zero?
94
- puts 'Built'
95
- # Find the gem build artifact
96
- gem_tar = Dir.glob('puppet-strings-*.gem').max_by { |f| File.mtime(f) }
97
- raise "Unable to find package in 'puppet-strings-*.gem'" if gem_tar.nil?
98
- gem_tar = File.expand_path(gem_tar)
99
-
100
- target_string = if args[:target_node_name].nil?
101
- 'all'
102
- else
103
- args[:target_node_name]
104
- end
105
- # TODO: Currently this is Linux targets only. no windows localhost
106
- tmp_path = '/tmp/'
107
- puts 'Copying gem to targets...'
108
- run_local_command("bolt file upload #{gem_tar} #{tmp_path}#{File.basename(gem_tar)} --targets #{target_string} --inventoryfile inventory.yaml")
109
-
110
- # Install dependent gems
111
- puts 'Installing yard gem...'
112
- install_remote_gem('yard', target_nodes, inventory_hash)
113
- puts 'Installing rgen gem...'
114
- install_remote_gem('rgen', target_nodes, inventory_hash)
115
- # Install puppet-strings
116
- puts 'Installing puppet-strings gem...'
117
- install_remote_gem(tmp_path + File.basename(gem_tar), target_nodes, inventory_hash)
118
- puts 'Installed'
119
- end
120
- end
121
-
122
- task(:rubocop) do
123
- require 'rubocop'
124
- cli = RuboCop::CLI.new
125
- result = cli.run(%w(-D -f s))
126
- abort unless result == RuboCop::CLI::STATUS_SUCCESS
127
- end
128
-
129
- #### CHANGELOG ####
130
- begin
131
- require 'github_changelog_generator/task'
132
- GitHubChangelogGenerator::RakeTask.new :changelog do |config|
133
- require 'puppet-strings/version'
134
- config.future_release = "v#{PuppetStrings::VERSION}"
135
- config.header = "# Changelog\n\n" \
136
- "All significant changes to this repo will be summarized in this file.\n"
137
- config.configure_sections = {
138
- added: {
139
- prefix: "Added",
140
- labels: ["enhancement"]
141
- },
142
- fixed: {
143
- prefix: "Fixed",
144
- labels: ["bugfix"]
145
- },
146
- breaking: {
147
- prefix: "Changed",
148
- labels: ["backwards-incompatible"]
149
- }
150
- }
151
- config.exclude_labels = ['maintenance','incomplete']
152
- config.user = 'puppetlabs'
153
- config.project = 'puppet-strings'
154
- end
155
- rescue LoadError
156
- desc 'Install github_changelog_generator to get access to automatic changelog generation'
157
- task :changelog do
158
- raise 'Install github_changelog_generator to get access to automatic changelog generation'
159
- end
160
- end
@@ -1,3 +0,0 @@
1
- ---
2
- # disable comments, info can be gotten from the pr status updates, and the comment editing spams the hipchat notifications
3
- comment: false
@@ -1,40 +0,0 @@
1
- Send out announcements for major new feature releases, and high-impact bugfixes to <puppet-announce@googlegroups.com>, <puppet-dev@googlegroups.com>, <puppet-users@googlegroups.com>, <voxpupuli@groups.io>, and the puppet internal mailing lists <dev@puppet.com> and <tech-discuss@puppet.com>.
2
-
3
- Before sending, do check that all links are still valid. Feel free to adjust the text to match better with the circumstances of the release, or add other news that are relevant at the time. If you make changes, consider committing them here, for the benefit of future-you.
4
-
5
- The github rendering of the markdown seems to copy&paste acceptably into Google Inbox.
6
-
7
- The [CHANGELOG](https://github.com/puppetlabs/puppet-strings/blob/master/CHANGELOG.md) is a good starting point for finding enhancements and bug-fixes.
8
-
9
- ---
10
-
11
- Subject: [ANN] Puppet Strings vX.Y.Z Release
12
-
13
- Hi all,
14
-
15
- We're pleased to announce that version X.Y.Z of the Puppet Strings is being released today.
16
-
17
- Puppet Strings provides a simple way to extract source documentation into useful docs. It is provided as a Ruby gem to be referenced within modules. See the [README](https://github.com/puppetlabs/puppet-strings#installing-puppet-strings) for documentation on how to install and use it.
18
-
19
-
20
- The new release of Puppet Strings provides the following enhancements:
21
-
22
- * A
23
- * B
24
- * C
25
-
26
- The new release also contains the following notable bugfixes:
27
-
28
- * D
29
- * E
30
- * F
31
-
32
- See the [CHANGELOG](https://github.com/puppetlabs/puppet-strings/blob/master/CHANGELOG.md) for a full list of changes
33
-
34
- We encourage all module developers to review puppet-strings and use it when creating modules.
35
-
36
- Please let us know of your experiences with Puppet Strings, either here, on [Slack](https://slack.puppet.com/) (#forge-modules), or on the [github repo](https://github.com/puppetlabs/puppet-strings).
37
-
38
-
39
- Thanks,
40
- YOUR NAME
@@ -1,69 +0,0 @@
1
- require 'spec_helper_acceptance'
2
-
3
- describe 'Emitting JSON' do
4
- before(:all) do
5
- @test_module_path = sut_module_path(/Module test/)
6
- @remote_tmp_path = sut_tmp_path
7
- end
8
-
9
- let(:expected) do
10
- {
11
- "puppet_classes" => [],
12
- "data_types" => [],
13
- "data_type_aliases" => [],
14
- "defined_types" => [],
15
- "resource_types" => [],
16
- "providers" => [],
17
- "puppet_functions" => [
18
- "name" => "function3x",
19
- "file" => "#{@test_module_path}/lib/puppet/parser/functions/function3x.rb",
20
- "line" => 1,
21
- "type" => "ruby3x",
22
- "signatures" => [
23
- {
24
- "signature" =>"function3x()",
25
- "docstring" => {
26
- "text" => "This is the function documentation for `function3x`",
27
- "tags" => [
28
- {
29
- "tag_name"=>"return",
30
- "text"=>"",
31
- "types"=>["Any"]
32
- }
33
- ]
34
- }
35
- },
36
- ],
37
- "docstring" => {
38
- "text" => "This is the function documentation for `function3x`",
39
- "tags" => ["tag_name" => "return", "text" => "", "types" => ["Any"]]},
40
- "source" => "Puppet::Parser::Functions.newfunction(:function3x, :doc => \"This is the function documentation for `function3x`\") do |args|\nend"
41
- ],
42
- "puppet_tasks" => [],
43
- "puppet_plans" => []
44
- }
45
- end
46
-
47
- [
48
- { :title => '--format json and STDOUT', :cmd_line => '--format json' },
49
- { :title => '--emit-json-stdout', :cmd_line => '--emit-json-stdout' }
50
- ].each do |testcase|
51
- it "should emit JSON to stdout when using #{testcase[:title]}" do
52
- output = PuppetLitmus::PuppetHelpers.run_shell("puppet strings generate #{testcase[:cmd_line]} \"#{@test_module_path}/lib/puppet/parser/functions/function3x.rb\"").stdout.chomp
53
- expect(JSON.parse(output)).to eq(expected)
54
- end
55
- end
56
-
57
- [
58
- { :title => '--format json and --out', :cmd_line => '--format json --out "TMPFILE"' },
59
- { :title => '--emit-json', :cmd_line => '--emit-json "TMPFILE"' },
60
- ].each do |testcase|
61
- it "should write JSON to a file when using #{testcase[:title]}" do
62
- tmpfile = File.join(@remote_tmp_path, 'json_output.json')
63
- cmd = "puppet strings generate #{testcase[:cmd_line].gsub('TMPFILE', tmpfile)} \"#{@test_module_path}/lib/puppet/parser/functions/function3x.rb\""
64
- PuppetLitmus::PuppetHelpers.run_shell(cmd)
65
- output = JSON.parse(file(tmpfile).content)
66
- expect(output).to eq(expected)
67
- end
68
- end
69
- end
@@ -1,47 +0,0 @@
1
- require 'spec_helper_acceptance'
2
-
3
- describe 'Generating Markdown' do
4
- before(:all) do
5
- @test_module_path = sut_module_path(/Module test/)
6
- @remote_tmp_path = sut_tmp_path
7
- end
8
-
9
- expected = <<-EOF
10
- # Reference
11
-
12
- ## Classes
13
- * [`test`](#test): This class exists to serve as fixture data for testing the puppet strings face
14
-
15
- ## Classes
16
-
17
- ### test
18
-
19
- #### Examples
20
- ```puppet
21
- class { "test": }
22
- ```
23
-
24
- #### Parameters
25
-
26
- ##### `package_name`
27
-
28
- The name of the package
29
-
30
- ##### `service_name`
31
-
32
- The name of the service
33
-
34
- EOF
35
-
36
- it 'should render Markdown to stdout when using --format markdown' do
37
- skip('This test is broken. Does not output to STDOUT by default.')
38
- output = PuppetLitmus::PuppetHelpers.run_shell("puppet strings generate --format markdown \"#{@test_module_path}/manifests/init.pp\"").stdout.chomp
39
- expect(output).to eq(expected)
40
- end
41
-
42
- it 'should write Markdown to a file when using --format markdown and --out' do
43
- tmpfile = File.join(@remote_tmp_path, 'md_output.md')
44
- remote = PuppetLitmus::PuppetHelpers.run_shell("puppet strings generate --format markdown --out \"#{tmpfile}\" \"#{@test_module_path}/manifests/init.pp\"")
45
- expect(file(tmpfile)).to contain expected
46
- end
47
- end
@@ -1,88 +0,0 @@
1
- require 'spec_helper_acceptance'
2
- include PuppetLitmus # rubocop:disable Style/MixinUsage This is fine
3
-
4
- describe 'Generating module documentation using generate action' do
5
- before :all do
6
- # TODO: Linux only
7
- @sut_work_dir = PuppetLitmus::PuppetHelpers.run_shell("pwd").stdout.chomp
8
-
9
- test_module_path = sut_module_path(/Module test/)
10
- PuppetLitmus::PuppetHelpers.run_shell("puppet strings generate \"#{test_module_path}/**/*.{rb,pp}\"")
11
- end
12
-
13
- def expect_file_contain(path, expected_contents)
14
- file_path = File.join(@sut_work_dir, path)
15
- file_content = file(file_path).content
16
- expected_contents.each do |expected|
17
- expect(file_content).to include(expected)
18
- end
19
- end
20
-
21
- it 'should generate documentation for manifests' do
22
- expect_file_contain('doc/puppet_classes/test.html', ['Class: test'])
23
- end
24
-
25
- it 'should generate documentation for puppet functions' do
26
- skip('This test is failing. Appear to be legitimate failures.')
27
- expect_file_contain('doc/puppet_functions_puppet/test_3A_3Aadd.html', [
28
- 'Adds two integers together.',
29
- # These tests are failing. Appear to be legitimate failures.
30
- '<p>The first integer to add.</p>',
31
- '<p>The second integer to add.</p>',
32
- '<p>Returns the sum of x and y.</p>'
33
- ])
34
- end
35
-
36
- it 'should generate documentation for 3x functions' do
37
- expect_file_contain('doc/puppet_functions_ruby3x/function3x.html', ['This is the function documentation for <code>function3x</code>'])
38
- end
39
-
40
- it 'should generate documentation for 4x functions' do
41
- expect_file_contain('doc/puppet_functions_ruby4x/function4x.html', ['This is a function which is used to test puppet strings'])
42
- end
43
-
44
- it 'should generate documentation for custom types' do
45
- expect_file_contain('doc/puppet_types/database.html', [
46
- '<p>An example server resource type.</p>',
47
- '<p>The database file to use.</p>',
48
- '<p>Documentation for a dynamic property.</p>',
49
- '<p>The database server name.</p>',
50
- '<p>Documentation for a dynamic parameter.</p>',
51
- '<p>The provider supports encryption.</p>',
52
- ])
53
- end
54
-
55
- it 'should generate documentation for custom providers' do
56
- expect_file_contain('doc/puppet_providers_database/linux.html', [
57
- 'The database provider on Linux',
58
- '<tt>osfamily &mdash; linux</tt>',
59
- '<tt>database &mdash; /usr/bin/database</tt>',
60
- ])
61
- end
62
-
63
- it 'should generate documentation for puppet data types' do
64
- expect_file_contain('doc/puppet_types/database.html', [
65
- 'Resource Type: database',
66
- 'type/database.rb',
67
- 'An example server resource type.',
68
- ])
69
- end
70
-
71
- it 'should generate documentation for puppet data type aliases' do
72
- expect_file_contain('doc/puppet_data_type_aliases/Test_3A_3AElephant.html', [
73
- 'Data Type: Test::Elephant',
74
- 'types/elephant.pp',
75
- 'A simple elephant type.',
76
- ])
77
- end
78
-
79
- it 'should generate documentation for enum tag' do
80
- expect_file_contain('doc/puppet_classes/test.html', [
81
- '<p class="tag_title">Enum Options (<tt>myenum</tt>):</p>',
82
- '<span class="name">a</span>',
83
- "&mdash; <div class='inline'>\n<p>Option A</p>\n</div>",
84
- '<span class="name">b</span>',
85
- "&mdash; <div class='inline'>\n<p>Option B</p>\n</div>",
86
- ])
87
- end
88
- end
@@ -1,9 +0,0 @@
1
- # Adds two integers together.
2
- # @param x The first integer to add.
3
- # @param y The second integer to add.
4
- # @return [Integer] Returns the sum of x and y.
5
- # @example Example of adding two integers.
6
- # test::add(1, 2) => 3
7
- function test::add(Integer $x, Integer $y) {
8
- $x + $y
9
- }
@@ -1,5 +0,0 @@
1
- # function 4x
2
- #
3
- # This is a function which is used to test puppet strings
4
- Puppet::Functions.create_function(:function4x) do
5
- end
@@ -1,2 +0,0 @@
1
- Puppet::Parser::Functions.newfunction(:function3x, :doc => "This is the function documentation for `function3x`") do |args|
2
- end
@@ -1,9 +0,0 @@
1
- Puppet::Type.type(:database).provide :linux do
2
- confine 'osfamily' => 'linux'
3
- defaultfor 'osfamily' => 'linux'
4
- commands :database => '/usr/bin/database'
5
-
6
- desc 'The database provider on Linux.'
7
-
8
- # ...
9
- end
@@ -1,15 +0,0 @@
1
- # @!puppet.type.param [value1, value2, value3] my_param Documentation for a dynamic parameter.
2
- # @!puppet.type.property [foo, bar, baz] my_prop Documentation for a dynamic property.
3
- Puppet::Type.newtype(:database) do
4
- desc 'An example server resource type.'
5
- feature :encryption, 'The provider supports encryption.', methods: [:encrypt]
6
-
7
- newparam(:address) do
8
- isnamevar
9
- desc 'The database server name.'
10
- end
11
-
12
- newproperty(:file) do
13
- desc 'The database file to use.'
14
- end
15
- end