puppet-strings 2.1.0 → 2.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b656b5430c108d15ea909e2381ca758884b51c910505ab36880f76be538b5eff
-  data.tar.gz: 6951a084211bbdc7d0d760865acae0e839ceadadd8df337d33938097083b4bc1
+  metadata.gz: 543437ac3fd3177245de47e563235b3f99194299f1c1cf14132bed3850de5056
+  data.tar.gz: 4aaa21554b916ca541ae3ce04a21ab34912375499347a816292858915aa803cf
 SHA512:
-  metadata.gz: 0c359ad4b8a62e978e16f01cf17a50e86d9c011fc13ce3bde9757f2f57074d92c8df7b78119b88bd8551510adb3cf2cbe5adb5644e99e2415ed830d6744eccfe
-  data.tar.gz: ed4d414529d500e4dfa696271e757c4daecd3df98c89ab83b2c7f956ac16a1392779c3fcf0d601d1c91c70a75a0e8745ce36bfef6679dac9f36a7cc3428aca76
+  metadata.gz: c73e04ec0c084f0000751eaa618ed5daa0efcfebf101e1d63832ab46403d0eff01ab628c028eae368097d2b3500c2e869d292c0fa07ad4eb68392773125b3ddf
+  data.tar.gz: 2a40adbd4874289129cecca5164f65ce3021a83a7cc3559bd6a6b28e3154020e1a9cd5a076c119827072feb47e2f6fe562924cfd63158f4c3e924ba132e0ddcd

data/CHANGELOG.md

@@ -3,16 +3,90 @@
 All significant changes to this repo will be summarized in this file.
 
 
-## [v2.1.0](https://github.com/puppetlabs/puppet-strings/tree/v2.1.0) (2018-06-25)
+## [v2.5.0](https://github.com/puppetlabs/puppet-strings/tree/v2.5.0) (2020-07-15)
+
+[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))
+- Add checks to resource\_type handler and code objects [\#232](https://github.com/puppetlabs/puppet-strings/pull/232) ([scotje](https://github.com/scotje))
+- \(\#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)
+
+## [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 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))
+
+Fixed
+
+- \(PDOC-283\) Fix namespaced symbols [\#205](https://github.com/puppetlabs/puppet-strings/pull/205) ([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)
+
+Added
+
+- \(PDOC-272\) Add required features attribute [\#194](https://github.com/puppetlabs/puppet-strings/pull/194) ([kris-bosland](https://github.com/kris-bosland))
+- \(maint\) Implement a strings:generate:reference task [\#192](https://github.com/puppetlabs/puppet-strings/pull/192) ([ekohl](https://github.com/ekohl))
+- \(PDOC-265\) Add examples to function reference docs [\#188](https://github.com/puppetlabs/puppet-strings/pull/188) ([ekohl](https://github.com/ekohl))
+- \(PDOC-252\) Add describe features to puppet-strings face [\#183](https://github.com/puppetlabs/puppet-strings/pull/183) ([kris-bosland](https://github.com/kris-bosland))
+
+Fixed
+
+- \(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)
 
 [Full Changelog](https://github.com/puppetlabs/puppet-strings/compare/2.0.0...v2.1.0)
 
-**Implemented enhancements:**
+Added
 
 - \(PDOC-212, PDOC-213\) add support for @note and @todo [\#182](https://github.com/puppetlabs/puppet-strings/pull/182) ([eputnam](https://github.com/eputnam))
 - \(PDOC-255\) markdown table of contents update [\#181](https://github.com/puppetlabs/puppet-strings/pull/181) ([eputnam](https://github.com/eputnam))
 
-**Merged pull requests:**
+Fixed
 
 - \(PDOC-259\) relax ruby requirement to 2.1.0 from 2.1.9 [\#184](https://github.com/puppetlabs/puppet-strings/pull/184) ([DavidS](https://github.com/DavidS))
 
@@ -236,4 +310,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

@@ -7,7 +7,7 @@ module PuppetStrings
     types/**/*.pp
     lib/**/*.rb
     tasks/*.json
-    plans/*.pp
+    plans/**/*.pp
   ).freeze
 
   # Generates documentation.
@@ -27,8 +27,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 +43,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]
@@ -53,7 +53,7 @@ module PuppetStrings
     YARD::CLI::Yardoc.run(*args)
 
     # If outputting JSON, render the output
-    if options[:json]
+    if options[:json] && !options[:describe]
       render_json(file)
     end
 
@@ -61,6 +61,10 @@ module PuppetStrings
     if options[:markdown]
       render_markdown(file)
     end
+
+    if options[:describe]
+      render_describe(options[:describe_types], options[:describe_list], options[:providers])
+    end
   end
 
   def self.puppet_5?
@@ -77,6 +81,11 @@ module PuppetStrings
     PuppetStrings::Markdown.render(path)
   end
 
+  def self.render_describe(describe_types, list = false, providers = false)
+    require 'puppet-strings/describe'
+    PuppetStrings::Describe.render(describe_types, list, providers)
+  end
+
   # Runs the YARD documentation server.
   # @param [Array<String>] args The arguments to YARD.
   def self.run_server(*args)

data/lib/puppet-strings/describe.rb

@@ -0,0 +1,68 @@
+require 'json'
+require 'puppet-strings/json'
+
+# The module for command line documentation related functionality.
+module PuppetStrings::Describe
+  # Renders requested types or a summarized list in the current YARD registry to STDOUT.
+  # @param [Array] describe_types The list of names of the types to be displayed.
+  # @param [bool] list Create the summarized list instead of describing each type.
+  # @param [bool] providers Show details of the providers.
+  # @return [void]
+  def self.render(describe_types = [], list = false, providers = false)
+    document = {
+      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),        
+    }
+
+    if list
+      puts "These are the types known to puppet:"
+      document[:resource_types].each { |t| list_one_type(t) }
+    else
+      document[:providers] = YARD::Registry.all(:puppet_provider).sort_by!(&:name).map!(&:to_hash)
+
+      type_names = {}
+      describe_types.each { |name| type_names[name] = true }
+
+      document[:resource_types].each do |t|
+        show_one_type(t, providers) if type_names[t[:name].to_s]
+      end
+    end
+  end
+
+  def self.show_one_type(resource_type, providers = false)
+    puts "\n%{name}\n%{underscore}" % { name: resource_type[:name], underscore: "=" * resource_type[:name].length }
+    puts resource_type[:docstring][:text]
+
+    combined_list = (resource_type[:parameters].nil? ? [] : resource_type[:parameters]) +
+                    (resource_type[:properties].nil? ? [] : resource_type[:properties])
+
+    if combined_list.any?
+      puts "\nParameters\n----------"
+      combined_list.sort_by { |p| p[:name] }.each { |p| show_one_parameter(p) }
+      puts "\nProviders\n---------"
+    end
+    #Show providers here - list or provide details      
+  end
+
+  def self.show_one_parameter(parameter)
+    puts "\n- **%{name}**\n" % { name: parameter[:name] }
+    puts parameter[:description]
+    puts "Valid values are `%{values}`." % { values: parameter[:values].join("`, `") } unless parameter[:values].nil?
+    puts "Requires features %{required_features}." % { required_features: parameter[:required_features] } unless parameter[:required_features].nil?
+  end
+
+  def self.list_one_type(type)
+    targetlength = 48
+    shortento = targetlength - 4
+    contentstring = type[:docstring][:text]
+    end_of_line = contentstring.index("\n")  # "." gives closer results to old describeb, but breaks for '.k5login'
+    if !end_of_line.nil?
+      contentstring = contentstring[0..end_of_line]
+    end
+    if contentstring.length > targetlength
+      contentstring = contentstring[0..shortento] + ' ...'
+    end
+    
+    puts "%-15s - %-s" % [type[:name], contentstring]
+  end
+end

data/lib/puppet-strings/json.rb

@@ -8,6 +8,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),
@@ -26,42 +28,4 @@ module PuppetStrings::Json
       puts JSON.pretty_generate(document)
     end
   end
-
-  # Converts a list of tags into an array of hashes.
-  # @param [Array] tags List of tags to be converted into an array of hashes.
-  # @return [Array] Returns an array of tag hashes.
-  def self.tags_to_hashes(tags)
-    # Skip over the API tags that are public
-    tags.select { |t| (t.tag_name != 'api' || t.text != 'public') }.map do |t|
-      next t.to_hash if t.respond_to?(:to_hash)
-
-      tag = { tag_name: t.tag_name }
-      # grab nested information for @option tags
-      if tag[:tag_name] == 'option'
-        tag[:opt_name] = t.pair.name
-        tag[:opt_text] = t.pair.text
-        tag[:opt_types] = t.pair.types
-        tag[:parent] = t.name
-      end
-      tag[:text] = t.text if t.text
-      tag[:types] = t.types if t.types
-      tag[:name] = t.name if t.name
-      tag
-    end
-  end
-
-  # Converts a YARD::Docstring (or String) to a docstring hash for JSON output.
-  # @param [YARD::Docstring, String] docstring The docstring to convert to a hash.
-  # @param [Array] select_tags List of tags to select. Other tags will be filtered out.
-  # @return [Hash] Returns a hash representation of the given docstring.
-  def self.docstring_to_hash(docstring, select_tags=nil)
-    hash = {}
-    hash[:text] = docstring
-    if docstring.is_a? YARD::Docstring
-      tags = tags_to_hashes(docstring.tags.select { |t| select_tags.nil? || select_tags.include?(t.tag_name.to_sym) })
-
-      hash[:tags] = tags unless tags.empty?
-    end
-    hash
-  end
 end