puppet-strings 2.2.0 → 2.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 9556dd124a1f5f4dfcaf4457232efbea310988d8
-  data.tar.gz: 3ef01d946f16d66c1d3af2c32345a90364ef57c6
+SHA256:
+  metadata.gz: 9aa1aa13861fd95a237ca2abd1ef890dfbcba1b7757c2dd609d648b803df7a33
+  data.tar.gz: 55d8b1903917fcd24fbb53dbe1433449a75eb88544071fdf0e2bf2d0eeb2fe11
 SHA512:
-  metadata.gz: 516ae9d909f068fc6c25cbb0f8839b06a16509201bfb7081f0f9ee985088a740780495ce00d50ac5d1c12560ac6d35fad7d2234dc31fc206ad79aa3ce8d5ddbb
-  data.tar.gz: eb5ec2204cac028fa9a27d7c5536694e3f07669d854e7323dba6d03d7cfeff369b92358ee19d4db9cb43fcc44df0f57540b1b41080eca6f1e21fc759e1c8d011
+  metadata.gz: 394ad674391503b4a894857035fbe190678bba4b264d6093935005b22322beda448fb38470ba92acedb191e1faec8dab01ccd0cc14ba807ca5b39cc6bff6b2fc
+  data.tar.gz: 420511c57607c8d76eb2d3e8b6417a84d3ac4247c3fc64ddd83a23fa50aba570b1e984e1a67a3c56c929c4ac8aeebf84726cd14e39ad689405ee8726281ae1dd

data/CHANGELOG.md

@@ -3,6 +3,91 @@
 All significant changes to this repo will be summarized in this file.
 
 
+## [v2.6.0](https://github.com/puppetlabs/puppet-strings/tree/v2.6.0) (2021-01-18)
+
+[Full Changelog](https://github.com/puppetlabs/puppet-strings/compare/v2.5.0...v2.6.0)
+
+Added
+
+- Improved markdown templates [\#252](https://github.com/puppetlabs/puppet-strings/pull/252) ([kozl](https://github.com/kozl))
+
+Fixed
+
+- Do not fail in case return tag has no type specified [\#268](https://github.com/puppetlabs/puppet-strings/pull/268) ([tiandrey](https://github.com/tiandrey))
+- Handle a missing description gracefully [\#260](https://github.com/puppetlabs/puppet-strings/pull/260) ([scotje](https://github.com/scotje))
+- Fix ERB failure - parameters without descriptions [\#255](https://github.com/puppetlabs/puppet-strings/pull/255) ([trevor-vaughan](https://github.com/trevor-vaughan))
+- puppet\_function template: fix tags, source [\#249](https://github.com/puppetlabs/puppet-strings/pull/249) ([raemer](https://github.com/raemer))
+
+Changed
+
+- \(MAINT\) Drop Ruby 2.1.x and Puppet 4.x compatibility [\#253](https://github.com/puppetlabs/puppet-strings/pull/253) ([scotje](https://github.com/scotje))
+
+**Closed issues:**
+
+- Tags \(Parameter, Returns\) not generated in HTML output [\#248](https://github.com/puppetlabs/puppet-strings/issues/248)
+- Can we get 2.5.0 released please [\#244](https://github.com/puppetlabs/puppet-strings/issues/244)
+- Add supported\_features to puppet strings input/output for types [\#228](https://github.com/puppetlabs/puppet-strings/issues/228)
+- Provider attribute is missing in generated types documentation [\#227](https://github.com/puppetlabs/puppet-strings/issues/227)
+
+## [v2.5.0](https://github.com/puppetlabs/puppet-strings/tree/v2.5.0) (2020-07-16)
+
+[Full Changelog](https://github.com/puppetlabs/puppet-strings/compare/v2.4.0...v2.5.0)
+
+Added
+
+- \(GH-225\) Document functions in Puppet Datatypes [\#235](https://github.com/puppetlabs/puppet-strings/pull/235) ([glennsarti](https://github.com/glennsarti))
+- \(\#227\) Inject `provider` into params list for types with providers [\#231](https://github.com/puppetlabs/puppet-strings/pull/231) ([scotje](https://github.com/scotje))
+
+Fixed
+
+- \(\#242\) Wrap names in backticks when rendering to markdown [\#243](https://github.com/puppetlabs/puppet-strings/pull/243) ([scotje](https://github.com/scotje))
+- Eliminate trailing spaces w/o descriptions [\#224](https://github.com/puppetlabs/puppet-strings/pull/224) ([binford2k](https://github.com/binford2k))
+
+**Closed issues:**
+
+- text rendering as emojis in strings generated docs [\#242](https://github.com/puppetlabs/puppet-strings/issues/242)
+- Puppet Classes not Listed in Left Frame Contents [\#241](https://github.com/puppetlabs/puppet-strings/issues/241)
+- exec type in generated docs missing attributes `creates`, `onlyif` [\#229](https://github.com/puppetlabs/puppet-strings/issues/229)
+- \[Feature\] Document functions in Puppet Datatypes [\#225](https://github.com/puppetlabs/puppet-strings/issues/225)
+- Document usage [\#8](https://github.com/puppetlabs/puppet-strings/issues/8)
+- Need a search box on the main page [\#1](https://github.com/puppetlabs/puppet-strings/issues/1)
+
+**Merged pull requests:**
+
+- Release prep for v2.5.0 [\#245](https://github.com/puppetlabs/puppet-strings/pull/245) ([scotje](https://github.com/scotje))
+
+## [v2.4.0](https://github.com/puppetlabs/puppet-strings/tree/v2.4.0) (2020-02-20)
+
+[Full Changelog](https://github.com/puppetlabs/puppet-strings/compare/v2.3.1...v2.4.0)
+
+Added
+
+- Add checks to resource\_type handler and code objects [\#232](https://github.com/puppetlabs/puppet-strings/pull/232) ([scotje](https://github.com/scotje))
+- Add missing HTML output support for enum tag [\#218](https://github.com/puppetlabs/puppet-strings/pull/218) ([seanmil](https://github.com/seanmil))
+- \(PDOC-295\) Add @enum tag support for Enum data types [\#215](https://github.com/puppetlabs/puppet-strings/pull/215) ([seanmil](https://github.com/seanmil))
+- Expanded default search glob for plans. [\#214](https://github.com/puppetlabs/puppet-strings/pull/214) ([Raskil](https://github.com/Raskil))
+
+**Merged pull requests:**
+
+- \(MAINT\) Release prep for 2.4.0 [\#221](https://github.com/puppetlabs/puppet-strings/pull/221) ([scotje](https://github.com/scotje))
+
+## [v2.3.1](https://github.com/puppetlabs/puppet-strings/tree/v2.3.1) (2019-09-23)
+
+[Full Changelog](https://github.com/puppetlabs/puppet-strings/compare/v2.3.0...v2.3.1)
+
+Fixed
+
+- \(maint\) Use parameters method instead of json\['parameters'\] [\#211](https://github.com/puppetlabs/puppet-strings/pull/211) ([lucywyman](https://github.com/lucywyman))
+- \(PDOC-285\) Fix data\_type\_handler for errors and numbers [\#209](https://github.com/puppetlabs/puppet-strings/pull/209) ([glennsarti](https://github.com/glennsarti))
+
+## [v2.3.0](https://github.com/puppetlabs/puppet-strings/tree/v2.3.0) (2019-07-17)
+
+[Full Changelog](https://github.com/puppetlabs/puppet-strings/compare/v2.2.0...v2.3.0)
+
+Added
+
+- Add Puppet Data Type documentation [\#199](https://github.com/puppetlabs/puppet-strings/pull/199) ([glennsarti](https://github.com/glennsarti))
+
 ## [v2.2.0](https://github.com/puppetlabs/puppet-strings/tree/v2.2.0) (2019-04-05)
 
 [Full Changelog](https://github.com/puppetlabs/puppet-strings/compare/v2.1.0...v2.2.0)
@@ -16,6 +101,7 @@ Added
 
 Fixed
 
+- \(PDOC-283\) Fix namespaced symbols [\#205](https://github.com/puppetlabs/puppet-strings/pull/205) ([glennsarti](https://github.com/glennsarti))
 - \(PDOC-266\) Silence 'unexpected construct regexp\_literal' warning [\#189](https://github.com/puppetlabs/puppet-strings/pull/189) ([seanmil](https://github.com/seanmil))
 
 ## [v2.1.0](https://github.com/puppetlabs/puppet-strings/tree/v2.1.0) (2018-06-26)
@@ -251,4 +337,4 @@ All related tickets can be found under the [PDOC][PDOC JIRA] JIRA project with t
 - Strings will no longer crash when documenting 3x functions with less than two arguments passed into newfunction **(PDOC-27)**
 
 
-\* *This Changelog was automatically generated by [github_changelog_generator](https://github.com/skywinder/Github-Changelog-Generator)*
+\* *This Changelog was automatically generated by [github_changelog_generator](https://github.com/github-changelog-generator/github-changelog-generator)*

data/CONTRIBUTING.md

@@ -7,13 +7,44 @@ that we can have a chance of keeping on top of things.
 
 ## Getting Started
 
-* Make sure you have a [Jira account](http://tickets.puppetlabs.com)
 * Make sure you have a [GitHub account](https://github.com/signup/free)
 * Submit a ticket for your issue, assuming one does not already exist.
   * Clearly describe the issue including steps to reproduce when it is a bug.
   * Make sure you fill in the earliest version that you know has the issue.
 * Fork the repository on GitHub
 
+## Submit an issue
+
+We use GitHub Issues for issue tracking on puppet-strings.
+
+Before you submit your issue, take a minute to...
+
+1. **Use the GitHub issue search** — check if the issue has already been
+   reported.
+
+2. **Check if the issue has been fixed** — try to reproduce it using the
+   latest `master` or release tag.
+
+A good bug report shouldn't leave others needing to chase you up for more
+information. Please try to be as **detailed as possible** in your issue. What is
+your environment? What steps will reproduce the issue? 
+
+Example:
+
+> Short and descriptive example issue title
+>
+> A summary of the issue with details about the environment it occurs in (Ruby version, Puppet version, Strings version, etc). If
+> suitable, include the steps required to reproduce the bug.
+>
+> 1. This is the first step
+> 2. This is the second step
+> 3. Further steps, etc.
+>
+> Any other information you want to share that is relevant to the issue being
+> reported. This might include the lines of code that you have identified as
+> causing the bug, and potential solutions (and your opinions on their
+> merits).
+
 ## Making Changes
 
 * 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:
 # Additional Resources
 
 * [More information on contributing](http://links.puppet.com/contribute-to-puppet)
-* [Bug tracker (Jira)](http://tickets.puppet.com)
 * [Contributor License Agreement](http://links.puppet.com/cla)
 * [General GitHub documentation](http://help.github.com/)
 * [GitHub pull request documentation](http://help.github.com/send-pull-requests/)

data/README.md

@@ -8,36 +8,43 @@ Puppet Strings generates documentation for Puppet code and extensions written in
 |                |                                                                 |
 | -------------- |---------------------------------------------------------------- |
 | *Code*         | [GitHub][repo]                                                  |
-| *Issues*       | [Puppet JIRA Tracker][JIRA]                                     |
+| *Issues*       | [GitHub issues][issues]                                         |
 | *License*      | [Apache 2.0][LICENSE]                                           |
 | *Change log*   | [CHANGELOG.md][changelog]                                       |
 | *Contributing* | [CONTRIBUTING.md][contributing] and [COMMITTERS.md][committers] |
 
-[repo]: https://github.com/puppetlabs/puppet-strings
-[JIRA]: https://tickets.puppetlabs.com/browse/PDOC
-[LICENSE]: https://github.com/puppetlabs/puppet-strings/blob/master/LICENSE
-[changelog]: https://github.com/puppetlabs/puppet-strings/blob/master/CHANGELOG.md
-[contributing]: https://github.com/puppetlabs/puppet-strings/blob/master/CONTRIBUTING.md
-[committers]: https://github.com/puppetlabs/puppet-strings/blob/master/COMMITTERS.md
-
 ## Installing Puppet Strings
 
 ### Requirements
 
   * Ruby 2.1.9 or newer
-  * Puppet 4.0 or newer
-  * The `yard` Ruby gem
+  * Puppet 4.0.0 or newer
 
 ### Install Puppet Strings
 
-1. Install the YARD gem by running `gem install yard`
-1. Install the `puppet-strings` gem by running `gem install puppet-strings`
-1. **Optional**: Set YARD options for Strings
+Installation instructions vary slightly depending on how you have installed Puppet:
+
+#### Installing Puppet Strings with [`puppet-agent`](https://puppet.com/docs/puppet/6.4/about_agent.html#what-puppet-agent-and-puppetserver-are) package
+
+Install the `puppet-strings` gem into the `puppet-agent` environment:
+
+```
+sudo /opt/puppetlabs/puppet/bin/gem install puppet-strings
+```
+
+#### Installing Puppet Strings with standalone `puppet` gem
 
-   To use YARD options with Puppet Strings, specify a `yardopts` file in the same directory in which you run `puppet strings`. Puppet Strings supports the Markdown format and automatically sets the YARD `markup` option to `markdown`.
+Install the `puppet-strings` gem into the same Ruby installation where you have installed the `puppet` gem:
 
-   To see a list of available YARD options, run `yard help doc`. For details about YARD options configuration, see the [YARD docs](http://www.rubydoc.info/gems/yard/file/docs/GettingStarted.md#config).
+```
+gem install puppet-strings
+```
 
+### Configure Puppet Strings (Optional)
+
+ To use YARD options with Puppet Strings, specify a `.yardopts` file in the same directory in which you run `puppet strings`. Puppet Strings supports the Markdown format and automatically sets the YARD `markup` option to `markdown`.
+
+ To see a list of available YARD options, run `yard help doc`. For details about YARD options configuration, see the [YARD docs](http://www.rubydoc.info/gems/yard/file/docs/GettingStarted.md#config).
 
 ## Generating documentation with Puppet Strings
 
@@ -74,12 +81,69 @@ To run specs, run the `spec` rake task:
     $ bundle install --path .bundle/gems
     $ bundle exec rake spec
 
+### Running Acceptance Tests
+
+We are experimenting with a new tool for running acceptance tests. It's name is [puppet_litmus](https://github.com/puppetlabs/puppet_litmus) and replaces beaker as the test runner.
+
+An example of running the acceptance tests locally with Docker:
+
+1. Ensure [Docker](https://www.docker.com/products/docker-desktop) is installed and running.
+
+2. Install Ruby gems. This step can be skipped if you have already followed the [Running Specs](#running-specs) instructions
+
+``` text
+    $ bundle install --path .bundle/gems
+```
+
+3. Provision a docker container, in this case CentOS 7
+
+``` text
+    $ bundle exec rake litmus:provision[docker, centos:7]
+```
+
+4. Install test items; Puppet Agent, our test module, and the puppet-strings gem built from this source code
+
+``` text
+    $ bundle exec rake litmus:install_agent[puppet6]
+    $ bundle exec rake litmus:install_module_fixtures
+    $ bundle exec rake litmus:install_gems
+```
+
+5. Run the acceptance tests. These tests can be run more than once without the need to run the provisioning steps again
+
+``` text
+    $ bundle exec rake litmus:acceptance:parallel
+```
+
+6. Remove any test containers
+
+``` text
+    $ bundle exec rake litmus:tear_down
+```
+
+The [Litmus Wiki](https://github.com/puppetlabs/puppet_litmus/wiki) contains more indepth information about Litmus. There is also a tutorial on using Litmus with an example [Puppet Module](https://github.com/puppetlabs/puppet_litmus/wiki/Tutorial:-use-Litmus-to-execute-acceptance-tests-with-a-sample-module-(MoTD)#install-the-necessary-gems-for-the-module)
+
+
+An example of run the acceptance tests follow the instructions [here].
+
 ## Support
 
-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.
+Please log issues in [GitHub issues][issues]. Check out [CONTRIBUTING.md][contributing] for tips on writing _the best_ issues.
 
-There is also an active #puppet channel on the Freenode IRC network.
+A [mailing list](https://groups.google.com/forum/?fromgroups#!forum/puppet-users) is available for asking questions and getting help from others.
+
+There is also an active community on the [Puppet community Slack][] in the #forge-modules channel.
 
 We use semantic version numbers for our releases and recommend that users upgrade to patch releases and minor releases as they become available.
 
 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.
+
+
+[repo]: https://github.com/puppetlabs/puppet-strings
+[issues]: https://github.com/puppetlabs/puppet-strings/issues
+[LICENSE]: https://github.com/puppetlabs/puppet-strings/blob/master/LICENSE
+[changelog]: https://github.com/puppetlabs/puppet-strings/blob/master/CHANGELOG.md
+[contributing]: https://github.com/puppetlabs/puppet-strings/blob/master/CONTRIBUTING.md
+[committers]: https://github.com/puppetlabs/puppet-strings/blob/master/COMMITTERS.md
+[Puppet community Slack]: https://slack.puppet.com
+

data/lib/puppet-strings.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 # The root module for Puppet Strings.
 module PuppetStrings
   # The glob patterns used to search for files to document.
@@ -7,7 +9,7 @@ module PuppetStrings
     types/**/*.pp
     lib/**/*.rb
     tasks/*.json
-    plans/*.pp
+    plans/**/*.pp
   ).freeze
 
   # Generates documentation.
@@ -27,8 +29,9 @@ module PuppetStrings
 
     # Format the arguments to YARD
     args = ['doc']
+    args << '--no-progress'
     args << '--debug'     if options[:debug]
-    args << '--backtrace' if options[:backtrace]
+    args << '--backtrace' if options[:debug]
     args << "-m#{options[:markup] || 'markdown'}"
 
     file = nil
@@ -42,7 +45,6 @@ module PuppetStrings
       args << '-n'
       args << '-q' unless file
       args << '--no-stats' unless file
-      args << '--no-progress' unless file
     end
 
     yard_args = options[:yard_args]

data/lib/puppet-strings/describe.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'json'
 require 'puppet-strings/json'
 

data/lib/puppet-strings/json.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'json'
 
 # The module for JSON related functionality.
@@ -8,6 +10,8 @@ module PuppetStrings::Json
   def self.render(file = nil)
     document = {
       puppet_classes: YARD::Registry.all(:puppet_class).sort_by!(&:name).map!(&:to_hash),
+      data_types: YARD::Registry.all(:puppet_data_type).sort_by!(&:name).map!(&:to_hash),
+      data_type_aliases: YARD::Registry.all(:puppet_data_type_alias).sort_by!(&:name).map!(&:to_hash),
       defined_types: YARD::Registry.all(:puppet_defined_type).sort_by!(&:name).map!(&:to_hash),
       resource_types: YARD::Registry.all(:puppet_type).sort_by!(&:name).map!(&:to_hash),
       providers: YARD::Registry.all(:puppet_provider).sort_by!(&:name).map!(&:to_hash),

data/lib/puppet-strings/markdown.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings/json'
 
 # module for parsing Yard Registries and generating markdown
@@ -5,6 +7,7 @@ module PuppetStrings::Markdown
   require_relative 'markdown/puppet_classes'
   require_relative 'markdown/functions'
   require_relative 'markdown/defined_types'
+  require_relative 'markdown/data_types'
   require_relative 'markdown/resource_types'
   require_relative 'markdown/puppet_tasks'
   require_relative 'markdown/puppet_plans'
@@ -13,15 +16,16 @@ module PuppetStrings::Markdown
   # generates markdown documentation
   # @return [String] markdown doc
   def self.generate
-    final = "# Reference\n"
-    final << "<!-- DO NOT EDIT: This document was generated by Puppet Strings -->\n\n"
-    final << PuppetStrings::Markdown::TableOfContents.render
-    final << PuppetStrings::Markdown::PuppetClasses.render
-    final << PuppetStrings::Markdown::DefinedTypes.render
-    final << PuppetStrings::Markdown::ResourceTypes.render
-    final << PuppetStrings::Markdown::Functions.render
-    final << PuppetStrings::Markdown::PuppetTasks.render
-    final << PuppetStrings::Markdown::PuppetPlans.render
+    final = "# Reference\n\n"
+    final += "<!-- DO NOT EDIT: This document was generated by Puppet Strings -->\n\n"
+    final += PuppetStrings::Markdown::TableOfContents.render
+    final += PuppetStrings::Markdown::PuppetClasses.render
+    final += PuppetStrings::Markdown::DefinedTypes.render
+    final += PuppetStrings::Markdown::ResourceTypes.render
+    final += PuppetStrings::Markdown::Functions.render
+    final += PuppetStrings::Markdown::DataTypes.render
+    final += PuppetStrings::Markdown::PuppetTasks.render
+    final += PuppetStrings::Markdown::PuppetPlans.render
 
     final
   end

data/lib/puppet-strings/markdown/base.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require 'puppet-strings'
 require 'puppet-strings/json'
 require 'puppet-strings/yard'
@@ -68,7 +70,7 @@ module PuppetStrings::Markdown
 
     # @return [String] top-level name
     def name
-      @registry[:name].to_s unless @registry[:name].nil?
+      @registry[:name]&.to_s
     end
 
     # @return [String] 'Overview' text (untagged text)
@@ -111,6 +113,11 @@ module PuppetStrings::Markdown
       select_tags('option')
     end
 
+    # @return [Array] enum tag hashes
+    def enums
+      select_tags('enum')
+    end
+
     # @param parameter_name
     #   parameter name to match to option tags
     # @return [Array] option tag hashes that have a parent parameter_name
@@ -119,6 +126,14 @@ module PuppetStrings::Markdown
       opts_for_p unless opts_for_p.nil? || opts_for_p.length.zero?
     end
 
+    # @param parameter_name
+    #   parameter name to match to enum tags
+    # @return [Array] enum tag hashes that have a parent parameter_name
+    def enums_for_param(parameter_name)
+      enums_for_p = enums.select { |e| e[:parent] == parameter_name } unless enums.nil?
+      enums_for_p unless enums_for_p.nil? || enums_for_p.length.zero?
+    end
+
     # @return [Hash] any defaults found for the component
     def defaults
       @registry[:defaults] unless @registry[:defaults].nil?
@@ -156,10 +171,22 @@ module PuppetStrings::Markdown
       @tags.any? { |tag| tag[:tag_name] == 'api' && tag[:text] == 'private' }
     end
 
+    def word_wrap(text, line_width: 120, break_sequence: "\n")
+      return unless text
+
+      text.split("\n").collect! do |line|
+        line.length > line_width ? line.gsub(/(.{1,#{line_width}})(\s+|$)/, "\\1#{break_sequence}").strip : line
+      end * break_sequence
+    end
+
     # @return [String] full markdown rendering of a component
     def render(template)
-      file = File.join(File.dirname(__FILE__),"templates/#{template}")
-      ERB.new(File.read(file), nil, '-').result(binding)
+      begin
+        file = File.join(File.dirname(__FILE__),"templates/#{template}")
+        ERB.new(File.read(file), nil, '-').result(binding)
+      rescue StandardError => e
+        fail "Processing #{@registry[:file]}:#{@registry[:line]} with #{file} => #{e}"
+      end
     end
 
     private