puppet-strings 2.3.1 → 2.4.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (31) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +10 -0
  3. data/CONTRIBUTING.md +32 -2
  4. data/Gemfile +7 -1
  5. data/README.md +15 -10
  6. data/Rakefile +44 -52
  7. data/lib/puppet-strings.rb +1 -1
  8. data/lib/puppet-strings/markdown/base.rb +13 -0
  9. data/lib/puppet-strings/markdown/templates/classes_and_defines.erb +8 -0
  10. data/lib/puppet-strings/markdown/templates/data_type.erb +8 -0
  11. data/lib/puppet-strings/markdown/templates/function.erb +8 -0
  12. data/lib/puppet-strings/markdown/templates/resource_type.erb +16 -0
  13. data/lib/puppet-strings/version.rb +1 -1
  14. data/lib/puppet-strings/yard.rb +6 -0
  15. data/lib/puppet-strings/yard/code_objects/function.rb +2 -2
  16. data/lib/puppet-strings/yard/tags.rb +2 -0
  17. data/lib/puppet-strings/yard/tags/enum_tag.rb +12 -0
  18. data/lib/puppet-strings/yard/tags/factory.rb +16 -0
  19. data/lib/puppet-strings/yard/templates/default/tags/html/enum.erb +17 -0
  20. data/lib/puppet-strings/yard/templates/default/tags/setup.rb +6 -0
  21. data/lib/puppet-strings/yard/util.rb +3 -3
  22. data/spec/acceptance/emit_json_options_spec.rb +2 -2
  23. data/spec/acceptance/generate_markdown_spec.rb +2 -2
  24. data/spec/acceptance/running_strings_generate_spec.rb +12 -2
  25. data/spec/fixtures/acceptance/modules/test/manifests/init.pp +4 -0
  26. data/spec/fixtures/unit/markdown/output.md +55 -2
  27. data/spec/fixtures/unit/markdown/output_with_data_types.md +55 -2
  28. data/spec/fixtures/unit/markdown/output_with_plan.md +55 -2
  29. data/spec/spec_helper_acceptance_local.rb +1 -1
  30. data/spec/unit/puppet-strings/markdown_spec.rb +20 -3
  31. metadata +6 -3
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: d8e021936451f50bd6d90032ebb46117245b1be028c0e717a02bb54ceb682194
4
- data.tar.gz: 2ae779863af3e9882d2d5c6a0609cfb4fd994a2683429a9f62a271762e58828d
3
+ metadata.gz: 9bfc095b6c7aa9124cfa44c79aa0404361fbe9b3971e58495aa8354f1b84163a
4
+ data.tar.gz: 56c425e69b8bd4b1e9c6a0bb07a25ca806d880e6e9a865afa8137d12b5412442
5
5
  SHA512:
6
- metadata.gz: 4795376753de54d5157d4b040781e9b2c322a777efa62b0400968ec895cb6a5aba32c20d19c374f9a5ab4c06b6fdcf6256f9c722684b356f1b64907194487f22
7
- data.tar.gz: 564f9d8ec0b7db59f46c882358c3126ad7d98f9629c4760f96b496f94563af69f69dcc0560fcb6465c88c0104aca6dd8d1df2342740b626a3c3e9fc80f3b90a3
6
+ metadata.gz: 0a0fcbc8af4653fb35166cad42488f21bf5f046092ef1434331c7d4ba03fa4ac2544c3e220859c9dc2de94b4a263caed7b35a6185df297bf6dbb631553601f9d
7
+ data.tar.gz: 7cf9f63f1fd50af678f4b3891ed7ac9da3d5eda249de6df50dd10ac93eed078f1f7fab6b5ca6945e6e057e89ce55c227b4aba1aab84884e6d89b1f039677ed38
@@ -3,6 +3,16 @@
3
3
  All significant changes to this repo will be summarized in this file.
4
4
 
5
5
 
6
+ ## [v2.4.0](https://github.com/puppetlabs/puppet-strings/tree/v2.4.0) (2020-02-18)
7
+
8
+ [Full Changelog](https://github.com/puppetlabs/puppet-strings/compare/v2.3.1...v2.4.0)
9
+
10
+ Added
11
+
12
+ - Add missing HTML output support for enum tag [\#218](https://github.com/puppetlabs/puppet-strings/pull/218) ([seanmil](https://github.com/seanmil))
13
+ - \(PDOC-295\) Add @enum tag support for Enum data types [\#215](https://github.com/puppetlabs/puppet-strings/pull/215) ([seanmil](https://github.com/seanmil))
14
+ - Expanded default search glob for plans. [\#214](https://github.com/puppetlabs/puppet-strings/pull/214) ([Raskil](https://github.com/Raskil))
15
+
6
16
  ## [v2.3.1](https://github.com/puppetlabs/puppet-strings/tree/v2.3.1) (2019-09-23)
7
17
 
8
18
  [Full Changelog](https://github.com/puppetlabs/puppet-strings/compare/v2.3.0...v2.3.1)
@@ -7,13 +7,44 @@ that we can have a chance of keeping on top of things.
7
7
 
8
8
  ## Getting Started
9
9
 
10
- * Make sure you have a [Jira account](http://tickets.puppetlabs.com)
11
10
  * Make sure you have a [GitHub account](https://github.com/signup/free)
12
11
  * Submit a ticket for your issue, assuming one does not already exist.
13
12
  * Clearly describe the issue including steps to reproduce when it is a bug.
14
13
  * Make sure you fill in the earliest version that you know has the issue.
15
14
  * Fork the repository on GitHub
16
15
 
16
+ ## Submit an issue
17
+
18
+ We use GitHub Issues for issue tracking on puppet-strings.
19
+
20
+ Before you submit your issue, take a minute to...
21
+
22
+ 1. **Use the GitHub issue search** — check if the issue has already been
23
+ reported.
24
+
25
+ 2. **Check if the issue has been fixed** — try to reproduce it using the
26
+ latest `master` or release tag.
27
+
28
+ A good bug report shouldn't leave others needing to chase you up for more
29
+ information. Please try to be as **detailed as possible** in your issue. What is
30
+ your environment? What steps will reproduce the issue?
31
+
32
+ Example:
33
+
34
+ > Short and descriptive example issue title
35
+ >
36
+ > A summary of the issue with details about the environment it occurs in (Ruby version, Puppet version, Strings version, etc). If
37
+ > suitable, include the steps required to reproduce the bug.
38
+ >
39
+ > 1. This is the first step
40
+ > 2. This is the second step
41
+ > 3. Further steps, etc.
42
+ >
43
+ > Any other information you want to share that is relevant to the issue being
44
+ > reported. This might include the lines of code that you have identified as
45
+ > causing the bug, and potential solutions (and your opinions on their
46
+ > merits).
47
+
17
48
  ## Making Changes
18
49
 
19
50
  * Create a topic branch from where you want to base your work.
@@ -98,7 +129,6 @@ To cut a new release, from a current `master` checkout:
98
129
  # Additional Resources
99
130
 
100
131
  * [More information on contributing](http://links.puppet.com/contribute-to-puppet)
101
- * [Bug tracker (Jira)](http://tickets.puppet.com)
102
132
  * [Contributor License Agreement](http://links.puppet.com/cla)
103
133
  * [General GitHub documentation](http://help.github.com/)
104
134
  * [GitHub pull request documentation](http://help.github.com/send-pull-requests/)
data/Gemfile CHANGED
@@ -24,7 +24,13 @@ end
24
24
 
25
25
  group :acceptance do
26
26
  # Litmus has dependencies which require Ruby 2.5 (Puppet 6) or above.
27
- gem 'puppet_litmus' if Gem::Version.new(RUBY_VERSION.dup) >= Gem::Version.new('2.5.0')
27
+ if Gem::Version.new(RUBY_VERSION.dup) >= Gem::Version.new('2.5.0')
28
+ # Until https://github.com/puppetlabs/puppet_litmus/pull/248 is merged we need to use the source of the
29
+ # of the PR. Not the greatest and prone to error, but without it, all litmus based testing is broken.
30
+ # This can be reverted once this PR is merged and Litmus is released with this fix.
31
+ gem 'puppet_litmus', git: 'https://github.com/michaeltlombardi/puppet_litmus', ref: 'maint/master/fix-upload-file'
32
+ gem 'net-ssh', '~> 5.2'
33
+ end
28
34
  end
29
35
 
30
36
  group :development do
data/README.md CHANGED
@@ -8,18 +8,11 @@ Puppet Strings generates documentation for Puppet code and extensions written in
8
8
  | | |
9
9
  | -------------- |---------------------------------------------------------------- |
10
10
  | *Code* | [GitHub][repo] |
11
- | *Issues* | [Puppet JIRA Tracker][JIRA] |
11
+ | *Issues* | [GitHub issues][issues] |
12
12
  | *License* | [Apache 2.0][LICENSE] |
13
13
  | *Change log* | [CHANGELOG.md][changelog] |
14
14
  | *Contributing* | [CONTRIBUTING.md][contributing] and [COMMITTERS.md][committers] |
15
15
 
16
- [repo]: https://github.com/puppetlabs/puppet-strings
17
- [JIRA]: https://tickets.puppetlabs.com/browse/PDOC
18
- [LICENSE]: https://github.com/puppetlabs/puppet-strings/blob/master/LICENSE
19
- [changelog]: https://github.com/puppetlabs/puppet-strings/blob/master/CHANGELOG.md
20
- [contributing]: https://github.com/puppetlabs/puppet-strings/blob/master/CONTRIBUTING.md
21
- [committers]: https://github.com/puppetlabs/puppet-strings/blob/master/COMMITTERS.md
22
-
23
16
  ## Installing Puppet Strings
24
17
 
25
18
  ### Requirements
@@ -135,10 +128,22 @@ An example of run the acceptance tests follow the instructions [here].
135
128
 
136
129
  ## Support
137
130
 
138
- Please log tickets and issues in our [JIRA tracker][JIRA]. A [mailing list](https://groups.google.com/forum/?fromgroups#!forum/puppet-users) is available for asking questions and getting help from others.
131
+ Please log issues in [GitHub issues][issues]. Check out [CONTRIBUTING.md][contributing] for tips on writing _the best_ issues.
139
132
 
140
- There is also an active #puppet channel on the Freenode IRC network.
133
+ A [mailing list](https://groups.google.com/forum/?fromgroups#!forum/puppet-users) is available for asking questions and getting help from others.
134
+
135
+ There is also an active community on the [Puppet community Slack][] in the #forge-modules channel.
141
136
 
142
137
  We use semantic version numbers for our releases and recommend that users upgrade to patch releases and minor releases as they become available.
143
138
 
144
139
  Bug fixes and ongoing development will occur in minor releases for the current major version. Security fixes will be ported to a previous major version on a best-effort basis, until the previous major version is no longer maintained.
140
+
141
+
142
+ [repo]: https://github.com/puppetlabs/puppet-strings
143
+ [issues]: https://github.com/puppetlabs/puppet-strings/issues
144
+ [LICENSE]: https://github.com/puppetlabs/puppet-strings/blob/master/LICENSE
145
+ [changelog]: https://github.com/puppetlabs/puppet-strings/blob/master/CHANGELOG.md
146
+ [contributing]: https://github.com/puppetlabs/puppet-strings/blob/master/CONTRIBUTING.md
147
+ [committers]: https://github.com/puppetlabs/puppet-strings/blob/master/COMMITTERS.md
148
+ [Puppet community Slack]: https://slack.puppet.com
149
+
data/Rakefile CHANGED
@@ -1,4 +1,39 @@
1
- require 'puppet_litmus/rake_tasks' if Bundler.rubygems.find_name('puppet_litmus').any?
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
+
2
37
  require 'puppetlabs_spec_helper/tasks/fixtures'
3
38
  require 'bundler/gem_tasks'
4
39
  require 'puppet-lint/tasks/puppet-lint'
@@ -25,53 +60,6 @@ task :validate do
25
60
  end
26
61
 
27
62
  namespace :litmus do
28
- # Install the puppet module fixture on a collection of nodes
29
- #
30
- # @param :target_node_name [Array] nodes on which to install a puppet module for testing.
31
- desc 'install_module_fixtures - build and install module fixtures'
32
- task :install_module_fixtures, [:target_node_name] do |_task, args|
33
- inventory_hash = inventory_hash_from_inventory_file
34
- target_nodes = find_targets(inventory_hash, args[:target_node_name])
35
- if target_nodes.empty?
36
- puts 'No targets found'
37
- exit 0
38
- end
39
- include BoltSpec::Run
40
- require 'pdk/module/build'
41
-
42
- module_fixture_dir = File.expand_path(File.join(File.dirname(__FILE__), 'spec', 'fixtures', 'acceptance', 'modules', 'test'))
43
- module_tar = nil
44
- Dir.chdir(module_fixture_dir) do
45
- opts = {}
46
- opts[:force] = true
47
- builder = PDK::Module::Build.new(opts)
48
- module_tar = builder.build
49
- puts 'Built'
50
- module_tar = Dir.glob('pkg/*.tar.gz').max_by { |f| File.mtime(f) }
51
- raise "Unable to find package in 'pkg/*.tar.gz'" if module_tar.nil?
52
- module_tar = File.expand_path(module_tar)
53
- end
54
-
55
- target_string = if args[:target_node_name].nil?
56
- 'all'
57
- else
58
- args[:target_node_name]
59
- end
60
- # TODO: Currently this is Linux only
61
- tmp_path = '/tmp/'
62
- run_local_command("bundle exec bolt file upload #{module_tar} #{tmp_path}#{File.basename(module_tar)} --nodes #{target_string} --inventoryfile inventory.yaml")
63
- install_module_command = "puppet module install #{tmp_path}#{File.basename(module_tar)}"
64
- result = run_command(install_module_command, target_nodes, config: nil, inventory: inventory_hash)
65
- if result.is_a?(Array)
66
- result.each do |node|
67
- puts "#{node['node']} failed #{node['result']}" if node['status'] != 'success'
68
- end
69
- else
70
- raise "Failed trying to run '#{install_module_command}' against inventory."
71
- end
72
- puts 'Installed'
73
- end
74
-
75
63
  def install_remote_gem(gem_name, target_nodes, inventory_hash)
76
64
  # TODO: Currently this is Linux only
77
65
  install_command = "/opt/puppetlabs/puppet/bin/gem install #{gem_name}"
@@ -96,6 +84,7 @@ namespace :litmus do
96
84
  puts 'No targets found'
97
85
  exit 0
98
86
  end
87
+ require 'bolt_spec/run'
99
88
  include BoltSpec::Run
100
89
 
101
90
  # Build the gem
@@ -113,15 +102,18 @@ namespace :litmus do
113
102
  else
114
103
  args[:target_node_name]
115
104
  end
116
- # TODO: Currently this is Linux only
105
+ # TODO: Currently this is Linux targets only. no windows localhost
117
106
  tmp_path = '/tmp/'
118
- run_local_command("bundle exec bolt file upload #{gem_tar} #{tmp_path}#{File.basename(gem_tar)} --nodes #{target_string} --inventoryfile inventory.yaml")
119
-
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")
120
109
 
121
110
  # Install dependent gems
111
+ puts 'Installing yard gem...'
122
112
  install_remote_gem('yard', target_nodes, inventory_hash)
113
+ puts 'Installing rgen gem...'
123
114
  install_remote_gem('rgen', target_nodes, inventory_hash)
124
115
  # Install puppet-strings
116
+ puts 'Installing puppet-strings gem...'
125
117
  install_remote_gem(tmp_path + File.basename(gem_tar), target_nodes, inventory_hash)
126
118
  puts 'Installed'
127
119
  end
@@ -156,7 +148,7 @@ begin
156
148
  labels: ["backwards-incompatible"]
157
149
  }
158
150
  }
159
- config.exclude_labels = ['maintenance']
151
+ config.exclude_labels = ['maintenance','incomplete']
160
152
  config.user = 'puppetlabs'
161
153
  config.project = 'puppet-strings'
162
154
  end
@@ -7,7 +7,7 @@ module PuppetStrings
7
7
  types/**/*.pp
8
8
  lib/**/*.rb
9
9
  tasks/*.json
10
- plans/*.pp
10
+ plans/**/*.pp
11
11
  ).freeze
12
12
 
13
13
  # Generates documentation.
@@ -111,6 +111,11 @@ module PuppetStrings::Markdown
111
111
  select_tags('option')
112
112
  end
113
113
 
114
+ # @return [Array] enum tag hashes
115
+ def enums
116
+ select_tags('enum')
117
+ end
118
+
114
119
  # @param parameter_name
115
120
  # parameter name to match to option tags
116
121
  # @return [Array] option tag hashes that have a parent parameter_name
@@ -119,6 +124,14 @@ module PuppetStrings::Markdown
119
124
  opts_for_p unless opts_for_p.nil? || opts_for_p.length.zero?
120
125
  end
121
126
 
127
+ # @param parameter_name
128
+ # parameter name to match to enum tags
129
+ # @return [Array] enum tag hashes that have a parent parameter_name
130
+ def enums_for_param(parameter_name)
131
+ enums_for_p = enums.select { |e| e[:parent] == parameter_name } unless enums.nil?
132
+ enums_for_p unless enums_for_p.nil? || enums_for_p.length.zero?
133
+ end
134
+
122
135
  # @return [Hash] any defaults found for the component
123
136
  def defaults
124
137
  @registry[:defaults] unless @registry[:defaults].nil?
@@ -65,6 +65,14 @@ Options:
65
65
  * **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %>
66
66
  <% end -%>
67
67
 
68
+ <% end -%>
69
+ <% if enums_for_param(param[:name]) -%>
70
+ Options:
71
+
72
+ <% enums_for_param(param[:name]).each do |e| -%>
73
+ * **<%= e[:opt_name] %>**: <%= e[:opt_text] %>
74
+ <% end -%>
75
+
68
76
  <% end -%>
69
77
  <% if defaults && defaults[param[:name]] -%>
70
78
  Default value: <%= value_string(defaults[param[:name]]) %>
@@ -69,6 +69,14 @@ Options:
69
69
  * **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %>
70
70
  <% end -%>
71
71
 
72
+ <% end -%>
73
+ <% if enums_for_param(param[:name]) -%>
74
+ Options:
75
+
76
+ <% enums_for_param(param[:name]).each do |e| -%>
77
+ * **<%= e[:opt_name] %>**: <%= e[:opt_text] %>
78
+ <% end -%>
79
+
72
80
  <% end -%>
73
81
  <% if defaults && defaults[param[:name]] -%>
74
82
  Default value: <%= value_string(defaults[param[:name]]) %>
@@ -87,6 +87,14 @@ Options:
87
87
  * **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %>
88
88
  <% end -%>
89
89
 
90
+ <% end -%>
91
+ <% if sig.enums_for_param(param[:name]) -%>
92
+ Options:
93
+
94
+ <% sig.enums_for_param(param[:name]).each do |e| -%>
95
+ * **<%= e[:opt_name] %>**: <%= e[:opt_text] %>
96
+ <% end -%>
97
+
90
98
  <% end -%>
91
99
  <% end -%>
92
100
  <% end -%>
@@ -77,6 +77,14 @@ Options:
77
77
  * **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %>
78
78
  <% end -%>
79
79
 
80
+ <% end -%>
81
+ <% if enums_for_param(prop[:name]) -%>
82
+ Options:
83
+
84
+ <% enums_for_param(prop[:name]).each do |e| -%>
85
+ * **<%= e[:opt_name] %>**: <%= e[:opt_text] %>
86
+ <% end -%>
87
+
80
88
  <% end -%>
81
89
  <% if prop[:default] -%>
82
90
  Default value: <%= prop[:default] %>
@@ -117,6 +125,14 @@ Options:
117
125
  * **<%= o[:opt_name] %>** `<%= o[:opt_types][0] %>`: <%= o[:opt_text] %>
118
126
  <% end -%>
119
127
 
128
+ <% end -%>
129
+ <% if enums_for_param(param[:name]) -%>
130
+ Options:
131
+
132
+ <% enums_for_param(param[:name]).each do |e| -%>
133
+ * **<%= e[:opt_name] %>**: <%= e[:opt_text] %>
134
+ <% end -%>
135
+
120
136
  <% end -%>
121
137
  <% if param[:default] -%>
122
138
  Default value: <%= value_string(param[:default]) %>
@@ -1,3 +1,3 @@
1
1
  module PuppetStrings
2
- VERSION = '2.3.1'.freeze
2
+ VERSION = '2.4.0'.freeze
3
3
  end
@@ -11,6 +11,9 @@ module PuppetStrings::Yard
11
11
  # Sets up YARD for use with puppet-strings.
12
12
  # @return [void]
13
13
  def self.setup!
14
+ # Register our factory
15
+ YARD::Tags::Library.default_factory = PuppetStrings::Yard::Tags::Factory
16
+
14
17
  # Register the template path
15
18
  YARD::Templates::Engine.register_template_path(File.join(File.dirname(__FILE__), 'yard', 'templates'))
16
19
 
@@ -30,6 +33,9 @@ module PuppetStrings::Yard
30
33
  # Register the summary tag
31
34
  PuppetStrings::Yard::Tags::SummaryTag.register!
32
35
 
36
+ # Register the enum tag
37
+ PuppetStrings::Yard::Tags::EnumTag.register!
38
+
33
39
  # Ignore documentation on Puppet DSL calls
34
40
  # This prevents the YARD DSL parser from emitting warnings for Puppet's Ruby DSL
35
41
  YARD::Handlers::Ruby::DSLHandlerMethods::IGNORE_METHODS['create_function'] = true
@@ -88,10 +88,10 @@ class PuppetStrings::Yard::CodeObjects::Function < PuppetStrings::Yard::CodeObje
88
88
  if self.has_tag? :overload
89
89
  # loop over overloads and append onto the signatures array
90
90
  self.tags(:overload).each do |o|
91
- hash[:signatures] << { :signature => o.signature, :docstring => PuppetStrings::Yard::Util.docstring_to_hash(o.docstring, %i[param option return example]) }
91
+ hash[:signatures] << { :signature => o.signature, :docstring => PuppetStrings::Yard::Util.docstring_to_hash(o.docstring, %i[param option enum return example]) }
92
92
  end
93
93
  else
94
- hash[:signatures] << { :signature => self.signature, :docstring => PuppetStrings::Yard::Util.docstring_to_hash(docstring, %i[param option return example]) }
94
+ hash[:signatures] << { :signature => self.signature, :docstring => PuppetStrings::Yard::Util.docstring_to_hash(docstring, %i[param option enum return example]) }
95
95
  end
96
96
 
97
97
  hash[:docstring] = PuppetStrings::Yard::Util.docstring_to_hash(docstring)
@@ -1,7 +1,9 @@
1
1
  # The module for custom YARD tags.
2
2
  module PuppetStrings::Yard::Tags
3
+ require 'puppet-strings/yard/tags/factory'
3
4
  require 'puppet-strings/yard/tags/parameter_directive'
4
5
  require 'puppet-strings/yard/tags/property_directive'
5
6
  require 'puppet-strings/yard/tags/overload_tag'
6
7
  require 'puppet-strings/yard/tags/summary_tag'
8
+ require 'puppet-strings/yard/tags/enum_tag'
7
9
  end
@@ -0,0 +1,12 @@
1
+ require 'yard/tags/option_tag'
2
+
3
+ # Implements an enum tag for describing enumerated value data types
4
+
5
+ class PuppetStrings::Yard::Tags::EnumTag < YARD::Tags::OptionTag
6
+ # Registers the tag with YARD.
7
+ # @return [void]
8
+ def self.register!
9
+ YARD::Tags::Library.define_tag("puppet.enum", :enum, :with_enums)
10
+ YARD::Tags::Library.visible_tags.place(:enum).after(:option)
11
+ end
12
+ end
@@ -0,0 +1,16 @@
1
+ require 'yard/tags/default_factory'
2
+ require 'puppet-strings/yard/tags/enum_tag'
3
+
4
+ class PuppetStrings::Yard::Tags::Factory < YARD::Tags::DefaultFactory
5
+
6
+ # Parses tag text and creates a new enum tag type. Modeled after
7
+ # the parse_tag_with_options method in YARD::Tags::DefaultFactory.
8
+ #
9
+ # @param tag_name the name of the tag to parse
10
+ # @param [String] text the raw tag text
11
+ # @return [Tag] a tag object with the tag_name, name, and nested Tag as type
12
+ def parse_tag_with_enums(tag_name, text)
13
+ name, text = *extract_name_from_text(text)
14
+ PuppetStrings::Yard::Tags::EnumTag.new(tag_name, name, parse_tag_with_name(tag_name, text))
15
+ end
16
+ end
@@ -0,0 +1,17 @@
1
+ <% if object.has_tag?(:enum) %>
2
+ <% object.parameters.each do |param, default| %>
3
+ <% tags = object.tags(:enum).select {|x| x.name.to_s == param.to_s.sub(/^\*+|:$/, '') } %>
4
+ <% next if tags.empty? %>
5
+ <p class="tag_title">Enum Options (<tt><%= param %></tt>):</p>
6
+ <ul class="option">
7
+ <% for tag in tags %>
8
+ <li>
9
+ <span class="name"><%= tag.pair.name %></span>
10
+ <% if tag.pair.text && tag.pair.text =~ /\S/ %>
11
+ &mdash; <%= htmlify_line(tag.pair.text) %>
12
+ <% end %>
13
+ </li>
14
+ <% end %>
15
+ </ul>
16
+ <% end %>
17
+ <% end %>
@@ -16,3 +16,9 @@ end
16
16
  def overload
17
17
  erb(if object.type == :puppet_function then :puppet_overload else :overload end)
18
18
  end
19
+
20
+ # Renders the enum section.
21
+ # @return [String] Returns the rendered section.
22
+ def enum
23
+ erb(:enum)
24
+ end
@@ -38,11 +38,11 @@ module PuppetStrings::Yard::Util
38
38
  next t.to_hash if t.respond_to?(:to_hash)
39
39
 
40
40
  tag = { tag_name: t.tag_name }
41
- # grab nested information for @option tags
42
- if tag[:tag_name] == 'option'
41
+ # grab nested information for @option and @enum tags
42
+ if tag[:tag_name] == 'option' || tag[:tag_name] == 'enum'
43
43
  tag[:opt_name] = t.pair.name
44
44
  tag[:opt_text] = t.pair.text
45
- tag[:opt_types] = t.pair.types
45
+ tag[:opt_types] = t.pair.types if t.pair.types
46
46
  tag[:parent] = t.name
47
47
  end
48
48
  tag[:text] = t.text if t.text
@@ -49,7 +49,7 @@ describe 'Emitting JSON' do
49
49
  { :title => '--emit-json-stdout', :cmd_line => '--emit-json-stdout' }
50
50
  ].each do |testcase|
51
51
  it "should emit JSON to stdout when using #{testcase[:title]}" do
52
- output = PuppetLitmus::Serverspec.run_shell("puppet strings generate #{testcase[:cmd_line]} \"#{@test_module_path}/lib/puppet/parser/functions/function3x.rb\"").stdout.chomp
52
+ output = PuppetLitmus::PuppetHelpers.run_shell("puppet strings generate #{testcase[:cmd_line]} \"#{@test_module_path}/lib/puppet/parser/functions/function3x.rb\"").stdout.chomp
53
53
  expect(JSON.parse(output)).to eq(expected)
54
54
  end
55
55
  end
@@ -61,7 +61,7 @@ describe 'Emitting JSON' do
61
61
  it "should write JSON to a file when using #{testcase[:title]}" do
62
62
  tmpfile = File.join(@remote_tmp_path, 'json_output.json')
63
63
  cmd = "puppet strings generate #{testcase[:cmd_line].gsub('TMPFILE', tmpfile)} \"#{@test_module_path}/lib/puppet/parser/functions/function3x.rb\""
64
- PuppetLitmus::Serverspec.run_shell(cmd)
64
+ PuppetLitmus::PuppetHelpers.run_shell(cmd)
65
65
  output = JSON.parse(file(tmpfile).content)
66
66
  expect(output).to eq(expected)
67
67
  end
@@ -35,13 +35,13 @@ The name of the service
35
35
 
36
36
  it 'should render Markdown to stdout when using --format markdown' do
37
37
  skip('This test is broken. Does not output to STDOUT by default.')
38
- output = PuppetLitmus::Serverspec.run_shell("puppet strings generate --format markdown \"#{@test_module_path}/manifests/init.pp\"").stdout.chomp
38
+ output = PuppetLitmus::PuppetHelpers.run_shell("puppet strings generate --format markdown \"#{@test_module_path}/manifests/init.pp\"").stdout.chomp
39
39
  expect(output).to eq(expected)
40
40
  end
41
41
 
42
42
  it 'should write Markdown to a file when using --format markdown and --out' do
43
43
  tmpfile = File.join(@remote_tmp_path, 'md_output.md')
44
- remote = PuppetLitmus::Serverspec.run_shell("puppet strings generate --format markdown --out \"#{tmpfile}\" \"#{@test_module_path}/manifests/init.pp\"")
44
+ remote = PuppetLitmus::PuppetHelpers.run_shell("puppet strings generate --format markdown --out \"#{tmpfile}\" \"#{@test_module_path}/manifests/init.pp\"")
45
45
  expect(file(tmpfile)).to contain expected
46
46
  end
47
47
  end
@@ -4,10 +4,10 @@ include PuppetLitmus # rubocop:disable Style/MixinUsage This is fine
4
4
  describe 'Generating module documentation using generate action' do
5
5
  before :all do
6
6
  # TODO: Linux only
7
- @sut_work_dir = PuppetLitmus::Serverspec.run_shell("pwd").stdout.chomp
7
+ @sut_work_dir = PuppetLitmus::PuppetHelpers.run_shell("pwd").stdout.chomp
8
8
 
9
9
  test_module_path = sut_module_path(/Module test/)
10
- PuppetLitmus::Serverspec.run_shell("puppet strings generate \"#{test_module_path}/**/*.{rb,pp}\"")
10
+ PuppetLitmus::PuppetHelpers.run_shell("puppet strings generate \"#{test_module_path}/**/*.{rb,pp}\"")
11
11
  end
12
12
 
13
13
  def expect_file_contain(path, expected_contents)
@@ -75,4 +75,14 @@ describe 'Generating module documentation using generate action' do
75
75
  'A simple elephant type.',
76
76
  ])
77
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
78
88
  end
@@ -7,9 +7,13 @@
7
7
  #
8
8
  # @param package_name The name of the package
9
9
  # @param service_name The name of the service
10
+ # @param myenum
11
+ # @enum myenum a Option A
12
+ # @enum myenum b Option B
10
13
  class test (
11
14
  $package_name = $test::params::package_name,
12
15
  $service_name = $test::params::service_name,
16
+ Enum['a', 'b'] $myenum = 'a',
13
17
 
14
18
  ) inherits test::params {
15
19
 
@@ -101,6 +101,19 @@ Third param.
101
101
 
102
102
  Default value: 'hi'
103
103
 
104
+ ##### `param4`
105
+
106
+ Data type: `Enum['one', 'two']`
107
+
108
+ Fourth param.
109
+
110
+ Options:
111
+
112
+ * **:one**: One option
113
+ * **:two**: Second option
114
+
115
+ Default value: 'two'
116
+
104
117
  ## Defined types
105
118
 
106
119
  ### klass::dt
@@ -162,6 +175,19 @@ Fourth param.
162
175
 
163
176
  Default value: `true`
164
177
 
178
+ ##### `param5`
179
+
180
+ Data type: `Enum['a', 'b']`
181
+
182
+ Fifth param.
183
+
184
+ Options:
185
+
186
+ * **:a**: Option A
187
+ * **:b**: Option B
188
+
189
+ Default value: 'a'
190
+
165
191
  ## Resource types
166
192
 
167
193
  ### apt_key
@@ -238,6 +264,11 @@ Aliases: "up"=>"present", "down"=>"absent"
238
264
 
239
265
  What state the database should be in.
240
266
 
267
+ Options:
268
+
269
+ * **:up**: Upstate
270
+ * **:down**: Downstate
271
+
241
272
  Default value: up
242
273
 
243
274
  ##### `file`
@@ -292,7 +323,7 @@ A simple Puppet function.
292
323
  $result = func(1, 2)
293
324
  ```
294
325
 
295
- #### `func(Integer $param1, Any $param2, String $param3 = hi)`
326
+ #### `func(Integer $param1, Any $param2, String $param3 = hi, Enum['yes', 'no'] $param4 = 'yes')`
296
327
 
297
328
  A simple Puppet function.
298
329
 
@@ -331,6 +362,17 @@ Options:
331
362
 
332
363
  * **:param3opt** `Array`: Something about this option
333
364
 
365
+ ##### `param4`
366
+
367
+ Data type: `Enum['yes', 'no']`
368
+
369
+ Fourth param.
370
+
371
+ Options:
372
+
373
+ * **:yes**: Yes option.
374
+ * **:no**: No option.
375
+
334
376
  ### func3x
335
377
 
336
378
  Type: Ruby 3.x API
@@ -391,7 +433,7 @@ $result = func4x(1, 'foo')
391
433
  $result = func4x(1, 'foo', ['bar'])
392
434
  ```
393
435
 
394
- #### `func4x(Integer $param1, Any $param2, Optional[Array[String]] $param3)`
436
+ #### `func4x(Integer $param1, Any $param2, Optional[Array[String]] $param3, Optional[Enum[one, two]] $param4)`
395
437
 
396
438
  An overview for the first overload.
397
439
 
@@ -428,6 +470,17 @@ Data type: `Optional[Array[String]]`
428
470
 
429
471
  The third parameter.
430
472
 
473
+ ##### `param4`
474
+
475
+ Data type: `Optional[Enum[one, two]]`
476
+
477
+ The fourth parameter.
478
+
479
+ Options:
480
+
481
+ * **:one**: Option one.
482
+ * **:two**: Option two.
483
+
431
484
  #### `func4x(Boolean $param, Callable &$block)`
432
485
 
433
486
  An overview for the second overload.
@@ -107,6 +107,19 @@ Third param.
107
107
 
108
108
  Default value: 'hi'
109
109
 
110
+ ##### `param4`
111
+
112
+ Data type: `Enum['one', 'two']`
113
+
114
+ Fourth param.
115
+
116
+ Options:
117
+
118
+ * **:one**: One option
119
+ * **:two**: Second option
120
+
121
+ Default value: 'two'
122
+
110
123
  ## Defined types
111
124
 
112
125
  ### klass::dt
@@ -168,6 +181,19 @@ Fourth param.
168
181
 
169
182
  Default value: `true`
170
183
 
184
+ ##### `param5`
185
+
186
+ Data type: `Enum['a', 'b']`
187
+
188
+ Fifth param.
189
+
190
+ Options:
191
+
192
+ * **:a**: Option A
193
+ * **:b**: Option B
194
+
195
+ Default value: 'a'
196
+
171
197
  ## Resource types
172
198
 
173
199
  ### apt_key
@@ -244,6 +270,11 @@ Aliases: "up"=>"present", "down"=>"absent"
244
270
 
245
271
  What state the database should be in.
246
272
 
273
+ Options:
274
+
275
+ * **:up**: Upstate
276
+ * **:down**: Downstate
277
+
247
278
  Default value: up
248
279
 
249
280
  ##### `file`
@@ -298,7 +329,7 @@ A simple Puppet function.
298
329
  $result = func(1, 2)
299
330
  ```
300
331
 
301
- #### `func(Integer $param1, Any $param2, String $param3 = hi)`
332
+ #### `func(Integer $param1, Any $param2, String $param3 = hi, Enum['yes', 'no'] $param4 = 'yes')`
302
333
 
303
334
  A simple Puppet function.
304
335
 
@@ -337,6 +368,17 @@ Options:
337
368
 
338
369
  * **:param3opt** `Array`: Something about this option
339
370
 
371
+ ##### `param4`
372
+
373
+ Data type: `Enum['yes', 'no']`
374
+
375
+ Fourth param.
376
+
377
+ Options:
378
+
379
+ * **:yes**: Yes option.
380
+ * **:no**: No option.
381
+
340
382
  ### func3x
341
383
 
342
384
  Type: Ruby 3.x API
@@ -397,7 +439,7 @@ $result = func4x(1, 'foo')
397
439
  $result = func4x(1, 'foo', ['bar'])
398
440
  ```
399
441
 
400
- #### `func4x(Integer $param1, Any $param2, Optional[Array[String]] $param3)`
442
+ #### `func4x(Integer $param1, Any $param2, Optional[Array[String]] $param3, Optional[Enum[one, two]] $param4)`
401
443
 
402
444
  An overview for the first overload.
403
445
 
@@ -434,6 +476,17 @@ Data type: `Optional[Array[String]]`
434
476
 
435
477
  The third parameter.
436
478
 
479
+ ##### `param4`
480
+
481
+ Data type: `Optional[Enum[one, two]]`
482
+
483
+ The fourth parameter.
484
+
485
+ Options:
486
+
487
+ * **:one**: Option one.
488
+ * **:two**: Option two.
489
+
437
490
  #### `func4x(Boolean $param, Callable &$block)`
438
491
 
439
492
  An overview for the second overload.
@@ -105,6 +105,19 @@ Third param.
105
105
 
106
106
  Default value: 'hi'
107
107
 
108
+ ##### `param4`
109
+
110
+ Data type: `Enum['one', 'two']`
111
+
112
+ Fourth param.
113
+
114
+ Options:
115
+
116
+ * **:one**: One option
117
+ * **:two**: Second option
118
+
119
+ Default value: 'two'
120
+
108
121
  ## Defined types
109
122
 
110
123
  ### klass::dt
@@ -166,6 +179,19 @@ Fourth param.
166
179
 
167
180
  Default value: `true`
168
181
 
182
+ ##### `param5`
183
+
184
+ Data type: `Enum['a', 'b']`
185
+
186
+ Fifth param.
187
+
188
+ Options:
189
+
190
+ * **:a**: Option A
191
+ * **:b**: Option B
192
+
193
+ Default value: 'a'
194
+
169
195
  ## Resource types
170
196
 
171
197
  ### apt_key
@@ -242,6 +268,11 @@ Aliases: "up"=>"present", "down"=>"absent"
242
268
 
243
269
  What state the database should be in.
244
270
 
271
+ Options:
272
+
273
+ * **:up**: Upstate
274
+ * **:down**: Downstate
275
+
245
276
  Default value: up
246
277
 
247
278
  ##### `file`
@@ -296,7 +327,7 @@ A simple Puppet function.
296
327
  $result = func(1, 2)
297
328
  ```
298
329
 
299
- #### `func(Integer $param1, Any $param2, String $param3 = hi)`
330
+ #### `func(Integer $param1, Any $param2, String $param3 = hi, Enum['yes', 'no'] $param4 = 'yes')`
300
331
 
301
332
  A simple Puppet function.
302
333
 
@@ -335,6 +366,17 @@ Options:
335
366
 
336
367
  * **:param3opt** `Array`: Something about this option
337
368
 
369
+ ##### `param4`
370
+
371
+ Data type: `Enum['yes', 'no']`
372
+
373
+ Fourth param.
374
+
375
+ Options:
376
+
377
+ * **:yes**: Yes option.
378
+ * **:no**: No option.
379
+
338
380
  ### func3x
339
381
 
340
382
  Type: Ruby 3.x API
@@ -395,7 +437,7 @@ $result = func4x(1, 'foo')
395
437
  $result = func4x(1, 'foo', ['bar'])
396
438
  ```
397
439
 
398
- #### `func4x(Integer $param1, Any $param2, Optional[Array[String]] $param3)`
440
+ #### `func4x(Integer $param1, Any $param2, Optional[Array[String]] $param3, Optional[Enum[one, two]] $param4)`
399
441
 
400
442
  An overview for the first overload.
401
443
 
@@ -432,6 +474,17 @@ Data type: `Optional[Array[String]]`
432
474
 
433
475
  The third parameter.
434
476
 
477
+ ##### `param4`
478
+
479
+ Data type: `Optional[Enum[one, two]]`
480
+
481
+ The fourth parameter.
482
+
483
+ Options:
484
+
485
+ * **:one**: Option one.
486
+ * **:two**: Option two.
487
+
435
488
  #### `func4x(Boolean $param, Callable &$block)`
436
489
 
437
490
  An overview for the second overload.
@@ -1,5 +1,5 @@
1
1
  def sut_module_path(module_regex)
2
- modules = JSON.parse(PuppetLitmus::Serverspec.run_shell('puppet module list --render-as json').stdout)
2
+ modules = JSON.parse(PuppetLitmus::PuppetHelpers.run_shell('puppet module list --render-as json').stdout)
3
3
  test_module_info = modules['modules_by_path'].values.flatten.find { |mod_info| mod_info =~ module_regex }
4
4
  test_module_info.match(/\(([^)]*)\)/)[1]
5
5
  end
@@ -29,11 +29,15 @@ describe PuppetStrings::Markdown do
29
29
  # @option param2 [String] :opt1 something about opt1
30
30
  # @option param2 [Hash] :opt2 a hash of stuff
31
31
  # @param param3 Third param.
32
+ # @param param4 Fourth param.
33
+ # @enum param4 :one One option
34
+ # @enum param4 :two Second option
32
35
  #
33
36
  class klass (
34
37
  Integer $param1 = 1,
35
38
  $param2 = undef,
36
- String $param3 = 'hi'
39
+ String $param3 = 'hi',
40
+ Enum['one', 'two'] $param4 = 'two',
37
41
  ) inherits foo::bar {
38
42
  }
39
43
 
@@ -58,11 +62,15 @@ class noparams () {}
58
62
  # @option param2 [Hash] :opt2 a hash of stuff
59
63
  # @param param3 Third param.
60
64
  # @param param4 Fourth param.
65
+ # @param param5 Fifth param.
66
+ # @enum param5 :a Option A
67
+ # @enum param5 :b Option B
61
68
  define klass::dt (
62
69
  Integer $param1 = 44,
63
70
  $param2,
64
71
  String $param3 = 'hi',
65
- Boolean $param4 = true
72
+ Boolean $param4 = true,
73
+ Enum['a', 'b'] $param5 = 'a'
66
74
  ) {
67
75
  }
68
76
  SOURCE
@@ -98,11 +106,14 @@ define klass::dt (
98
106
  # @param param2 Second param.
99
107
  # @param param3 Third param.
100
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.
101
112
  # @raise SomeError this is some error
102
113
  # @return [Undef] Returns nothing.
103
114
  # @example Test
104
115
  # $result = func(1, 2)
105
- function func(Integer $param1, $param2, String $param3 = hi) {
116
+ function func(Integer $param1, $param2, String $param3 = hi, Enum['yes', 'no'] $param4 = 'yes') {
106
117
  }
107
118
  SOURCE
108
119
 
@@ -122,6 +133,9 @@ Puppet::Functions.create_function(:func4x) do
122
133
  # @option param2 [String] :option an option
123
134
  # @option param2 [String] :option2 another option
124
135
  # @param param3 The third parameter.
136
+ # @param param4 The fourth parameter.
137
+ # @enum param4 :one Option one.
138
+ # @enum param4 :two Option two.
125
139
  # @return Returns nothing.
126
140
  # @example Calling the function foo
127
141
  # $result = func4x(1, 'foooo')
@@ -130,6 +144,7 @@ Puppet::Functions.create_function(:func4x) do
130
144
  param 'Integer', :param1
131
145
  param 'Any', :param2
132
146
  optional_param 'Array[String]', :param3
147
+ optional_param 'Enum[one, two]', :param4
133
148
  return_type 'Undef'
134
149
  end
135
150
 
@@ -183,6 +198,8 @@ Puppet::Type.newtype(:database) do
183
198
  desc <<-DESC
184
199
  An example database server type.
185
200
  @option opts :foo bar
201
+ @enum ensure :up Upstate
202
+ @enum ensure :down Downstate
186
203
  @raise SomeError
187
204
  @example here's an example
188
205
  database { 'foo':
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: puppet-strings
3
3
  version: !ruby/object:Gem::Version
4
- version: 2.3.1
4
+ version: 2.4.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Puppet Inc.
8
8
  autorequire:
9
9
  bindir: bin
10
10
  cert_chain: []
11
- date: 2019-09-23 00:00:00.000000000 Z
11
+ date: 2020-02-20 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: yard
@@ -128,6 +128,8 @@ files:
128
128
  - lib/puppet-strings/yard/parsers/puppet/parser.rb
129
129
  - lib/puppet-strings/yard/parsers/puppet/statement.rb
130
130
  - lib/puppet-strings/yard/tags.rb
131
+ - lib/puppet-strings/yard/tags/enum_tag.rb
132
+ - lib/puppet-strings/yard/tags/factory.rb
131
133
  - lib/puppet-strings/yard/tags/overload_tag.rb
132
134
  - lib/puppet-strings/yard/tags/parameter_directive.rb
133
135
  - lib/puppet-strings/yard/tags/property_directive.rb
@@ -217,6 +219,7 @@ files:
217
219
  - lib/puppet-strings/yard/templates/default/puppet_type/html/setup.rb
218
220
  - lib/puppet-strings/yard/templates/default/puppet_type/html/summary.erb
219
221
  - lib/puppet-strings/yard/templates/default/puppet_type/html/todo.erb
222
+ - lib/puppet-strings/yard/templates/default/tags/html/enum.erb
220
223
  - lib/puppet-strings/yard/templates/default/tags/html/puppet_overload.erb
221
224
  - lib/puppet-strings/yard/templates/default/tags/setup.rb
222
225
  - lib/puppet-strings/yard/util.rb
@@ -282,7 +285,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
282
285
  version: '0'
283
286
  requirements:
284
287
  - puppet, >= 4.0.0
285
- rubygems_version: 3.0.3
288
+ rubygems_version: 3.0.4
286
289
  signing_key:
287
290
  specification_version: 4
288
291
  summary: Puppet documentation via YARD