puppet-strings 1.1.1 → 1.2.0

Sign up to get free protection for your applications and to get access to all the features.
Files changed (42) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +21 -0
  3. data/Gemfile +4 -2
  4. data/README.md +53 -10
  5. data/codecov.yml +3 -0
  6. data/lib/puppet-strings.rb +30 -11
  7. data/lib/puppet-strings/json.rb +7 -0
  8. data/lib/puppet-strings/markdown.rb +35 -0
  9. data/lib/puppet-strings/markdown/base.rb +168 -0
  10. data/lib/puppet-strings/markdown/defined_type.rb +14 -0
  11. data/lib/puppet-strings/markdown/defined_types.rb +37 -0
  12. data/lib/puppet-strings/markdown/function.rb +52 -0
  13. data/lib/puppet-strings/markdown/functions.rb +38 -0
  14. data/lib/puppet-strings/markdown/puppet_class.rb +14 -0
  15. data/lib/puppet-strings/markdown/puppet_classes.rb +37 -0
  16. data/lib/puppet-strings/markdown/resource_type.rb +27 -0
  17. data/lib/puppet-strings/markdown/resource_types.rb +37 -0
  18. data/lib/puppet-strings/markdown/table_of_contents.rb +21 -0
  19. data/lib/puppet-strings/markdown/templates/classes_and_defines.erb +63 -0
  20. data/lib/puppet-strings/markdown/templates/function.erb +50 -0
  21. data/lib/puppet-strings/markdown/templates/resource_type.erb +114 -0
  22. data/lib/puppet-strings/markdown/templates/table_of_contents.erb +21 -0
  23. data/lib/puppet-strings/tasks/generate.rb +24 -5
  24. data/lib/puppet-strings/yard/code_objects/function.rb +3 -3
  25. data/lib/puppet-strings/yard/code_objects/type.rb +3 -1
  26. data/lib/puppet-strings/yard/handlers.rb +1 -0
  27. data/lib/puppet-strings/yard/handlers/puppet/function_handler.rb +1 -1
  28. data/lib/puppet-strings/yard/handlers/ruby/base.rb +1 -1
  29. data/lib/puppet-strings/yard/handlers/ruby/rsapi_handler.rb +141 -0
  30. data/lib/puppet/face/strings.rb +28 -7
  31. data/spec/acceptance/emit_json_options.rb +4 -4
  32. data/spec/acceptance/generate_markdown_spec.rb +49 -0
  33. data/spec/fixtures/unit/json/output.json +43 -0
  34. data/spec/fixtures/unit/markdown/output.md +383 -0
  35. data/spec/spec_helper.rb +19 -1
  36. data/spec/unit/puppet-strings/json_spec.rb +40 -0
  37. data/spec/unit/puppet-strings/markdown/base_spec.rb +146 -0
  38. data/spec/unit/puppet-strings/markdown_spec.rb +248 -0
  39. data/spec/unit/puppet-strings/yard/handlers/puppet/function_handler_spec.rb +16 -1
  40. data/spec/unit/puppet-strings/yard/handlers/ruby/provider_handler_spec.rb +1 -1
  41. data/spec/unit/puppet-strings/yard/handlers/ruby/rsapi_handler_spec.rb +213 -0
  42. metadata +38 -2
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA1:
3
- metadata.gz: 617d17b2ad3472b75cc4710c3041ff341f32f908
4
- data.tar.gz: b79393ed1448e9a68e870b1c7c26e5e1e0fa7cd3
3
+ metadata.gz: e0b022bc727dcda3a4a796595059fa42a79815f2
4
+ data.tar.gz: 00aebdc79f8e40a6149940a6e495e2cf3b2e356d
5
5
  SHA512:
6
- metadata.gz: fd878646dc1c5daa2d95cd60a8ee63ca1550862ee1cfefe333a826ba452b6ed5962460f49717cb754ee734b8a8a2aeab1a88b752b49ed358c05043da552ae6d6
7
- data.tar.gz: 4991c269e0354a10b447078f8714627c034b00bcbdc8db0a1d99243e9f1108fdb7a1367540abe79405a3d1ac255f1d6f16d461b0819f4abe8f47cf877a8d5e42
6
+ metadata.gz: c52b785c39bf5e539934a64aea7af0b9f1fe192f0caf6eb327e6c43926d1a9d943ef1ec4c1dec30ebacd779d2694d8bf8f55fc90472f37beb9d7d3dc15b84b3d
7
+ data.tar.gz: 89ee514938a2f69a69705c79b52598e5b9144a984dcf7ab6a5304dfab6a372fc3686b548936517cd135f7dc8ea13b8ef1951ebb1f430e6dab740384a5f26a191
@@ -1,3 +1,21 @@
1
+ # Change log
2
+
3
+ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](http://semver.org).
4
+
5
+ ## [1.2.0](https://github.com/puppetlabs/puppet-strings/tree/1.2.0) (2018-02-26)
6
+
7
+ [Full Changelog](https://github.com/puppetlabs/puppet-strings/compare/1.1.1...1.2.0)
8
+
9
+ ### Added
10
+
11
+ - \(PDOC-184\) generate markdown [\#156](https://github.com/puppetlabs/puppet-strings/pull/156) ([eputnam](https://github.com/eputnam))
12
+ - \(PDK-437\) Add support for Resource API types [\#153](https://github.com/puppetlabs/puppet-strings/pull/153) ([DavidS](https://github.com/DavidS))
13
+
14
+ ### Fixed
15
+
16
+ - Fix return type matching for Puppet functions [\#159](https://github.com/puppetlabs/puppet-strings/pull/159) ([pegasd](https://github.com/pegasd))
17
+ - Add rgen as a runtime dependency [\#149](https://github.com/puppetlabs/puppet-strings/pull/149) ([rnelson0](https://github.com/rnelson0))
18
+
1
19
  ## 2017-10-20 - Release 1.1.1
2
20
 
3
21
  ### BugFixes
@@ -166,3 +184,6 @@ All related tickets can be found under the [PDOC][PDOC JIRA] JIRA project with t
166
184
  - Puppet namespaces are no longer mangled for nested classes and defined types **(PDOC-25)**
167
185
  - Strings is now compatible with the renaming of the Puppetx/puppetx namespace to PuppetX/puppet_x **(PDOC-26)**
168
186
  - Strings will no longer crash when documenting 3x functions with less than two arguments passed into newfunction **(PDOC-27)**
187
+
188
+
189
+ \* *This Changelog was automatically generated by [github_changelog_generator](https://github.com/skywinder/Github-Changelog-Generator)*
data/Gemfile CHANGED
@@ -4,7 +4,7 @@ gemspec
4
4
 
5
5
  gem 'rgen'
6
6
  gem 'redcarpet'
7
- gem 'yard', '0.9.5'
7
+ gem 'yard', '~> 0.9.11'
8
8
 
9
9
  if ENV['PUPPET_GEM_VERSION']
10
10
  gem 'puppet', ENV['PUPPET_GEM_VERSION'], :require => false
@@ -13,10 +13,12 @@ else
13
13
  end
14
14
 
15
15
  group :test do
16
- gem "rspec", "~> 3.1"
16
+ gem 'codecov'
17
17
  gem 'mocha'
18
18
  gem 'puppetlabs_spec_helper'
19
19
  gem 'serverspec'
20
+ gem 'simplecov-console'
21
+ gem "rspec", "~> 3.1"
20
22
  end
21
23
 
22
24
  group :acceptance do
data/README.md CHANGED
@@ -162,17 +162,33 @@ Strings can produce documentation in JSON and then either generate a `.json` fil
162
162
  To generate JSON documentation to a file, run:
163
163
 
164
164
  ```
165
- $ puppet strings generate --emit-json documentation.json
165
+ $ puppet strings generate --format json --out documentation.json
166
166
  ```
167
167
 
168
168
  To generate and then print JSON documentation to stdout, run:
169
169
 
170
170
  ```
171
- $ puppet strings generate --emit-json-stdout
171
+ $ puppet strings generate --format json
172
172
  ```
173
173
 
174
174
  For details about Strings JSON output, see [Strings JSON schema](https://github.com/puppetlabs/puppet-strings/blob/master/JSON.md).
175
175
 
176
+ ### Output documents in Markdown
177
+
178
+ Strings can also produce documentation in Markdown and then either generate an `.md` file or print Markdown to stdout. The generated markdown layout has been reviewed and approved by Puppet's tech pubs team and is the same that is used in Puppet Supported modules.
179
+
180
+ To generate REFERENCE.md:
181
+
182
+ ```
183
+ $ puppet strings generate --format markdown
184
+ ```
185
+
186
+ To write Markdown documentation to another file, use the --out option:
187
+
188
+ ```
189
+ $ puppet strings generate --format markdown --out docs/INFO.md
190
+ ```
191
+
176
192
  ### Output documents to GitHub Pages
177
193
 
178
194
  To generate documents and then make them available on [GitHub Pages](https://pages.github.com/), use the Strings rake task `strings:gh_pages:update`. See [Rake tasks](#rake-tasks) for setup and usage details.
@@ -196,7 +212,7 @@ To document Puppet classes and defined types, use a series of comments to create
196
212
  # include example
197
213
  #
198
214
  # @param first The first parameter for this class
199
- # @param second The second paramter for this class
215
+ # @param second The second parameter for this class
200
216
  class example_class(
201
217
  String $first = $example::params::first_arg,
202
218
  Integer $second = $example::params::second_arg,
@@ -285,6 +301,35 @@ end
285
301
 
286
302
  All provider method calls, including `confine`, `defaultfor`, and `commands`, are automatically parsed and documented by Strings. The `desc` method is used to generate the docstring, and can include tags such as `@example` if written as a heredoc.
287
303
 
304
+ Document types that use the new [Resource API](https://github.com/puppetlabs/puppet-resource_api):
305
+
306
+ ```ruby
307
+ Puppet::ResourceApi.register_type(
308
+ name: 'database',
309
+ docs: 'An example database server resource type.',
310
+ attributes: {
311
+ ensure: {
312
+ type: 'Enum[present, absent, up, down]',
313
+ desc: 'What state the database should be in.',
314
+ default: 'up',
315
+ },
316
+ address: {
317
+ type: 'String',
318
+ desc: 'The database server name.',
319
+ behaviour: :namevar,
320
+ },
321
+ encrypt: {
322
+ type: 'Boolean',
323
+ desc: 'Whether or not to encrypt the database.',
324
+ default: false,
325
+ behaviour: :parameter,
326
+ },
327
+ },
328
+ )
329
+ ```
330
+
331
+ Here, the `docs` key acts like the `desc` method of the traditional resource type. Everything else is the same, except that now everything is a value in the data structure, not passed to methods.
332
+
288
333
  **Note**: Puppet Strings can not evaluate your Ruby code, so only certain static expressions are supported.
289
334
 
290
335
  ### Documenting functions
@@ -418,17 +463,15 @@ function example(string $name) {
418
463
 
419
464
  ### Available Strings tags
420
465
 
421
- The most commonly used tags for Strings are:
422
-
423
- * `@param`: Documents a parameter with a given name, type and optional description.
424
- * `@return`: Describes the return value (and type or types) of a method. You can list multiple return tags for a method if the method has distinct return cases. In this case, begin each case with "if".
466
+ * `@api`: Describes the resource as private or public, most commonly used with classes or defined types.
425
467
  * `@example`: Shows an example snippet of code for an object. The first line is an optional title. See above for more about how to [include examples in documentation](#including-examples-in-documentation).
468
+ * `@param`: Documents a parameter with a given name, type and optional description.
426
469
  * `@!puppet.type.param`: Documents dynamic type parameters. See [Documenting resource types and providers](#documenting-resource-types-and-providers) above.
427
470
  * `@!puppet.type.property`: Documents dynamic type properties. See [Documenting resource types and providers](#documenting-resource-types-and-providers) above.
428
- * `@since`: Lists the version in which the object was first added.
471
+ * `@return`: Describes the return value (and type or types) of a method. You can list multiple return tags for a method if the method has distinct return cases. In this case, begin each case with "if".
429
472
  * `@see`: Adds "see also" references. Accepts URLs or other code objects with an optional description at the end. Note that the URL or object is automatically linked by YARD and does not need markup formatting.
430
-
431
- For a complete list of tags, see the [YARD Tags Overview](http://www.rubydoc.info/gems/yard/file/docs/Tags.md).
473
+ * `@since`: Lists the version in which the object was first added.
474
+ * `@summary`: A short description of the documented item.
432
475
 
433
476
  ### Rake tasks
434
477
 
@@ -0,0 +1,3 @@
1
+ ---
2
+ # disable comments, info can be gotten from the pr status updates, and the comment editing spams the hipchat notifications
3
+ comment: false
@@ -14,7 +14,9 @@ module PuppetStrings
14
14
  # @option options [Boolean] :debug Enable YARD debug output.
15
15
  # @option options [Boolean] :backtrace Enable YARD backtraces.
16
16
  # @option options [String] :markup The YARD markup format to use (defaults to 'markdown').
17
- # @option options [String] :json Enables JSON output to the given file. If the file is nil, STDOUT is used.
17
+ # @option options [String] :path Write the selected format to a file path
18
+ # @option options [Boolean] :markdown From the --format option, is the format Markdown?
19
+ # @option options [Boolean] :json Is the format JSON?
18
20
  # @option options [Array<String>] :yard_args The arguments to pass to yard.
19
21
  # @return [void]
20
22
  def self.generate(search_patterns = DEFAULT_SEARCH_PATTERNS, options = {})
@@ -27,15 +29,18 @@ module PuppetStrings
27
29
  args << '--backtrace' if options[:backtrace]
28
30
  args << "-m#{options[:markup] || 'markdown'}"
29
31
 
30
- render_as_json = options.key? :json
31
- json_file = nil
32
- if render_as_json
33
- json_file = options[:json]
32
+ file = nil
33
+ if options[:json] || options[:markdown]
34
+ file = if options[:json]
35
+ options[:path]
36
+ elsif options[:markdown]
37
+ options[:path] || "REFERENCE.md"
38
+ end
34
39
  # Disable output and prevent stats/progress when writing to STDOUT
35
40
  args << '-n'
36
- args << '-q' unless json_file
37
- args << '--no-stats' unless json_file
38
- args << '--no-progress' unless json_file
41
+ args << '-q' unless file
42
+ args << '--no-stats' unless file
43
+ args << '--no-progress' unless file
39
44
  end
40
45
 
41
46
  yard_args = options[:yard_args]
@@ -46,10 +51,24 @@ module PuppetStrings
46
51
  YARD::CLI::Yardoc.run(*args)
47
52
 
48
53
  # If outputting JSON, render the output
49
- if render_as_json
50
- require 'puppet-strings/json'
51
- PuppetStrings::Json.render(json_file)
54
+ if options[:json]
55
+ render_json(file)
52
56
  end
57
+
58
+ # If outputting Markdown, render the output
59
+ if options[:markdown]
60
+ render_markdown(file)
61
+ end
62
+ end
63
+
64
+ def self.render_json(path)
65
+ require 'puppet-strings/json'
66
+ PuppetStrings::Json.render(path)
67
+ end
68
+
69
+ def self.render_markdown(path)
70
+ require 'puppet-strings/markdown'
71
+ PuppetStrings::Markdown.render(path)
53
72
  end
54
73
 
55
74
  # Runs the YARD documentation server.
@@ -34,6 +34,13 @@ module PuppetStrings::Json
34
34
  next t.to_hash if t.respond_to?(:to_hash)
35
35
 
36
36
  tag = { tag_name: t.tag_name }
37
+ # grab nested information for @option tags
38
+ if tag[:tag_name] == 'option'
39
+ tag[:opt_name] = t.pair.name
40
+ tag[:opt_text] = t.pair.text
41
+ tag[:opt_types] = t.pair.types
42
+ tag[:parent] = t.name
43
+ end
37
44
  tag[:text] = t.text if t.text
38
45
  tag[:types] = t.types if t.types
39
46
  tag[:name] = t.name if t.name
@@ -0,0 +1,35 @@
1
+ require 'puppet-strings/json'
2
+
3
+ # module for parsing Yard Registries and generating markdown
4
+ module PuppetStrings::Markdown
5
+ require_relative 'markdown/puppet_classes'
6
+ require_relative 'markdown/functions'
7
+ require_relative 'markdown/defined_types'
8
+ require_relative 'markdown/resource_types'
9
+ require_relative 'markdown/table_of_contents'
10
+
11
+ # generates markdown documentation
12
+ # @return [String] markdown doc
13
+ def self.generate
14
+ final = "# Reference\n\n"
15
+ final << PuppetStrings::Markdown::TableOfContents.render
16
+ final << PuppetStrings::Markdown::PuppetClasses.render
17
+ final << PuppetStrings::Markdown::DefinedTypes.render
18
+ final << PuppetStrings::Markdown::ResourceTypes.render
19
+ final << PuppetStrings::Markdown::Functions.render
20
+
21
+ final
22
+ end
23
+
24
+ # mimicks the behavior of the json render, although path will never be nil
25
+ # @param [String] path path to destination file
26
+ def self.render(path = nil)
27
+ if path.nil?
28
+ puts generate
29
+ exit
30
+ else
31
+ File.open(path, 'w') { |file| file.write(generate) }
32
+ YARD::Logger.instance.debug "Wrote markdown to #{path}"
33
+ end
34
+ end
35
+ end
@@ -0,0 +1,168 @@
1
+ require 'puppet-strings'
2
+ require 'puppet-strings/json'
3
+ require 'puppet-strings/yard'
4
+
5
+ module PuppetStrings::Markdown
6
+ # This class makes elements in a YARD::Registry hash easily accessible for templates.
7
+ #
8
+ # Here's an example hash:
9
+ #{:name=>:klass,
10
+ # :file=>"(stdin)",
11
+ # :line=>16,
12
+ # :inherits=>"foo::bar",
13
+ # :docstring=>
14
+ # {:text=>"An overview for a simple class.",
15
+ # :tags=>
16
+ # [{:tag_name=>"summary", :text=>"A simple class."},
17
+ # {:tag_name=>"since", :text=>"1.0.0"},
18
+ # {:tag_name=>"see", :name=>"www.puppet.com"},
19
+ # {:tag_name=>"example",
20
+ # :text=>
21
+ # "class { 'klass':\n" +
22
+ # " param1 => 1,\n" +
23
+ # " param3 => 'foo',\n" +
24
+ # "}",
25
+ # :name=>"This is an example"},
26
+ # {:tag_name=>"author", :text=>"eputnam"},
27
+ # {:tag_name=>"option", :name=>"opts"},
28
+ # {:tag_name=>"raise", :text=>"SomeError"},
29
+ # {:tag_name=>"param",
30
+ # :text=>"First param.",
31
+ # :types=>["Integer"],
32
+ # :name=>"param1"},
33
+ # {:tag_name=>"param",
34
+ # :text=>"Second param.",
35
+ # :types=>["Any"],
36
+ # :name=>"param2"},
37
+ # {:tag_name=>"param",
38
+ # :text=>"Third param.",
39
+ # :types=>["String"],
40
+ # :name=>"param3"}]},
41
+ # :defaults=>{"param1"=>"1", "param2"=>"undef", "param3"=>"'hi'"},
42
+ # :source=>
43
+ # "class klass (\n" +
44
+ # " Integer $param1 = 1,\n" +
45
+ # " $param2 = undef,\n" +
46
+ # " String $param3 = 'hi'\n" +
47
+ # ") inherits foo::bar {\n" +
48
+ # "}"}
49
+ class Base
50
+ def initialize(registry, component_type)
51
+ @type = component_type
52
+ @registry = registry
53
+ @tags = registry[:docstring][:tags] || []
54
+ end
55
+
56
+ # generate 1:1 tag methods
57
+ # e.g. {:tag_name=>"author", :text=>"eputnam"}
58
+ { :return_val => 'return',
59
+ :since => 'since',
60
+ :summary => 'summary' }.each do |method_name, tag_name|
61
+ # @return [String] unless the tag is nil or the string.length == 0
62
+ define_method method_name do
63
+ @tags.select { |tag| tag[:tag_name] == "#{tag_name}" }[0][:text] unless @tags.select { |tag| tag[:tag_name] == "#{tag_name}" }[0].nil? || @tags.select { |tag| tag[:tag_name] == "#{tag_name}" }[0][:text].length.zero?
64
+ end
65
+ end
66
+
67
+ # @return [String] top-level name
68
+ def name
69
+ @registry[:name].to_s unless @registry[:name].nil?
70
+ end
71
+
72
+ # @return [String] 'Overview' text (untagged text)
73
+ def text
74
+ @registry[:docstring][:text] unless @registry[:docstring][:text].empty?
75
+ end
76
+
77
+ # @return [String] data type of return value
78
+ def return_type
79
+ @tags.select { |tag| tag[:tag_name] == 'return' }[0][:types][0] unless @tags.select { |tag| tag[:tag_name] == 'return' }[0].nil?
80
+ end
81
+
82
+ # @return [String] text from @since tag
83
+ def since
84
+ @tags.select { |tag| tag[:tag_name] == 'since' }[0][:text] unless @tags.select { |tag| tag[:tag_name] == 'since' }[0].nil?
85
+ end
86
+
87
+ # @return [Array] @see tag hashes
88
+ def see
89
+ @tags.select { |tag| tag[:tag_name] == 'see' } unless @tags.select { |tag| tag[:tag_name] == 'see' }[0].nil?
90
+ end
91
+
92
+ # @return [Array] parameter tag hashes
93
+ def params
94
+ @tags.select { |tag| tag[:tag_name] == 'param' } unless @tags.select { |tag| tag[:tag_name] == 'param' }[0].nil?
95
+ end
96
+
97
+ # @return [Array] example tag hashes
98
+ def examples
99
+ @tags.select { |tag| tag[:tag_name] == 'example' } unless @tags.select { |tag| tag[:tag_name] == 'example' }[0].nil?
100
+ end
101
+
102
+ # @return [Array] raise tag hashes
103
+ def raises
104
+ @tags.select { |tag| tag[:tag_name] == 'raise' } unless @tags.select { |tag| tag[:tag_name] == 'raise' }[0].nil?
105
+ end
106
+
107
+ # @return [Array] option tag hashes
108
+ def options
109
+ @tags.select { |tag| tag[:tag_name] == 'option' } unless @tags.select { |tag| tag[:tag_name] == 'option' }[0].nil?
110
+ end
111
+
112
+ # @param parameter_name
113
+ # parameter name to match to option tags
114
+ # @return [Array] option tag hashes that have a parent parameter_name
115
+ def options_for_param(parameter_name)
116
+ opts_for_p = options.select { |o| o[:parent] == parameter_name } unless options.nil?
117
+ opts_for_p unless opts_for_p.nil? || opts_for_p.length.zero?
118
+ end
119
+
120
+ # @return [Array] any defaults found for the component
121
+ def defaults
122
+ @registry[:defaults] unless @registry[:defaults].nil?
123
+ end
124
+
125
+ # @return [Hash] information needed for the table of contents
126
+ def toc_info
127
+ {
128
+ name: name.to_s,
129
+ link: link,
130
+ desc: summary || @registry[:docstring][:text][0..140].gsub("\n",' '),
131
+ private: private?
132
+ }
133
+ end
134
+
135
+ # @return [String] makes the component name suitable for a GitHub markdown link
136
+ def link
137
+ name.delete('::').strip.gsub(' ','-').downcase
138
+ end
139
+
140
+ # Some return, default, or valid values need to be in backticks. Instead of fu in the handler or code_object, this just does the change on the front.
141
+ # @param value
142
+ # any string
143
+ # @return [String] value or value in backticks if it is in a list
144
+ def value_string(value)
145
+ to_symbol = %w[undef true false]
146
+ if to_symbol.include? value
147
+ return "`#{value}`"
148
+ else
149
+ return value
150
+ end
151
+ end
152
+
153
+ def private?
154
+ result = false
155
+ api = @tags.find { |tag| tag[:tag_name] == 'api' }
156
+ unless api.nil?
157
+ result = api[:text] == 'private' ? true : false
158
+ end
159
+ result
160
+ end
161
+
162
+ # @return [String] full markdown rendering of a component
163
+ def render(template)
164
+ file = File.join(File.dirname(__FILE__),"templates/#{template}")
165
+ ERB.new(File.read(file), nil, '-').result(binding)
166
+ end
167
+ end
168
+ end