puppet-strings 2.2.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 9556dd124a1f5f4dfcaf4457232efbea310988d8
-  data.tar.gz: 3ef01d946f16d66c1d3af2c32345a90364ef57c6
+SHA256:
+  metadata.gz: 8a70d1194ec3d0f50cc7924ce43b3d996b08db414a31639d38135c90863b3163
+  data.tar.gz: 821fef3a3e096caa7a3a51024db23e18658baba2b25bf4f503a750952e8e3657
 SHA512:
-  metadata.gz: 516ae9d909f068fc6c25cbb0f8839b06a16509201bfb7081f0f9ee985088a740780495ce00d50ac5d1c12560ac6d35fad7d2234dc31fc206ad79aa3ce8d5ddbb
-  data.tar.gz: eb5ec2204cac028fa9a27d7c5536694e3f07669d854e7323dba6d03d7cfeff369b92358ee19d4db9cb43fcc44df0f57540b1b41080eca6f1e21fc759e1c8d011
+  metadata.gz: 457119ac6a325f6c4f62923a6180b05d346b0e2d2b7e560b4cddfeda51f345284e98421abb46a68a2a3c0bd62933300394866d91247d69ef2b154667ffd91df3
+  data.tar.gz: db555eb951d97aa8ac62396693c9c9d317f4e361b4b9dd405d9b7d21d6ccda9f89beb70f292053e6f0440e02b6cf9fb2b8e5f9defb209a6920a7597337128834

data/CHANGELOG.md

@@ -3,6 +3,18 @@
 All significant changes to this repo will be summarized in this file.
 
 
+## [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)

data/Gemfile

@@ -23,10 +23,8 @@ group :test do
 end
 
 group :acceptance do
-  gem 'beaker', '< 3.0'
-  gem 'beaker-rspec'
-  gem 'beaker-hostgenerator'
-  gem 'beaker-abs'
+  # Litmus has dependencies which require Ruby 2.5 (Puppet 6) or above.
+  gem 'puppet_litmus' if Gem::Version.new(RUBY_VERSION.dup) >= Gem::Version.new('2.5.0')
 end
 
 group :development do
@@ -35,4 +33,15 @@ group :development do
   gem 'pry-byebug'
 end
 
-gem 'rubocop', '~> 0.49'
+gem 'rubocop-rspec'
+gem 'rubocop', '~> 0.57.2'
+
+# Evaluate Gemfile.local if it exists
+if File.exists? "#{__FILE__}.local"
+  eval(File.read("#{__FILE__}.local"), binding)
+end
+
+# Evaluate ~/.gemfile if it exists
+if File.exists?(File.join(Dir.home, '.gemfile'))
+  eval(File.read(File.join(Dir.home, '.gemfile')), binding)
+end

data/JSON.md

@@ -9,17 +9,19 @@ puppet strings generate --format json
 Document Schema
 ===============
 
-At the top level, there are seven arrays in the JSON document:
-
-| Document Key     | Description                                                                   |
-| ---------------- | ----------------------------------------------------------------------------- |
-| puppet_classes   | The list of Puppet classes that were parsed.                                  |
-| defined_types    | The list of defined types that were parsed.                                   |
-| resource_types   | The list of resource types that were parsed.                                  |
-| providers        | The list of resource providers that were parsed.                              |
-| puppet_functions | The list of Puppet functions (4.x, 4.x and Puppet language) that were parsed. |
-| puppet_tasks     | The list of Puppet tasks that were parsed.                                    |
-| puppet_plans     | The list of Puppet plans that were parsed.                                    |
+At the top level, there are nine arrays in the JSON document:
+
+| Document Key      | Description                                                                   |
+| ----------------- | ----------------------------------------------------------------------------- |
+| puppet_classes    | The list of Puppet classes that were parsed.                                  |
+| data_types        | The list of data types that were parsed.                                      |
+| data_type_aliases | | The list of data types that were parsed.                                      |
+| defined_types     | The list of defined types that were parsed.                                   |
+| resource_types    | The list of resource types that were parsed.                                  |
+| providers         | The list of resource providers that were parsed.                              |
+| puppet_functions  | The list of Puppet functions (4.x, 4.x and Puppet language) that were parsed. |
+| puppet_tasks      | The list of Puppet tasks that were parsed.                                    |
+| puppet_plans      | The list of Puppet plans that were parsed.                                    |
 
 Puppet Classes
 --------------
@@ -36,6 +38,34 @@ Each entry in the `puppet_classes` list is an object with the following attribut
 | defaults      | The map of parameter names to default values.         |
 | source        | The Puppet source code for the class.                 |
 
+Data Types
+----------
+
+Each entry in the `data_types` list is an object with the following attributes:
+
+| Attribute Key | Description                                                 |
+| ------------- | ----------------------------------------------------------- |
+| name          | The name of the data type.                                  |
+| file          | The file defining the data type.                            |
+| line          | The line where the data type is data.                       |
+| docstring     | The *DocString* object for the data type (see below).       |
+| defaults      | The map of parameter names to default values.               |
+| source        | The ruby source code for the data type. (Not Implemented)   |
+
+Data Type Aliases
+-----------------
+
+Each entry in the `data_type_aliases` list is an object with the following attributes:
+
+| Attribute Key | Description                                                       |
+| ------------- | ----------------------------------------------------------------- |
+| name          | The name of the data type.                                        |
+| file          | The file defining the data type.                                  |
+| line          | The line where the data type is defined.                          |
+| docstring     | The *DocString* object for the data type (see below).             |
+| alias_of      | The actual type this is an alias of.                              |
+| source        | The Puppet source code for the data type alias. (Not Implemented) |
+
 Defined Types
 -------------
 

data/README.md

@@ -25,19 +25,33 @@ Puppet Strings generates documentation for Puppet code and extensions written in
 ### 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:
 
-   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`.
+#### Installing Puppet Strings with [`puppet-agent`](https://puppet.com/docs/puppet/6.4/about_agent.html#what-puppet-agent-and-puppetserver-are) package
 
-   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).
+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
+
+Install the `puppet-strings` gem into the same Ruby installation where you have installed the `puppet` gem:
+
+```
+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,6 +88,51 @@ 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.

data/Rakefile

@@ -1,5 +1,6 @@
+require 'puppet_litmus/rake_tasks' if Bundler.rubygems.find_name('puppet_litmus').any?
+require 'puppetlabs_spec_helper/tasks/fixtures'
 require 'bundler/gem_tasks'
-#require 'puppetlabs_spec_helper/rake_tasks'
 require 'puppet-lint/tasks/puppet-lint'
 
 require 'rspec/core/rake_task'
@@ -23,45 +24,114 @@ task :validate do
   end
 end
 
-task :acceptance do
-  require 'beaker-hostgenerator'
+namespace :litmus do
+  # Install the puppet module fixture on a collection of nodes
+  #
+  # @param :target_node_name [Array] nodes on which to install a puppet module for testing.
+  desc 'install_module_fixtures - build and install module fixtures'
+  task :install_module_fixtures, [:target_node_name] do |_task, args|
+    inventory_hash = inventory_hash_from_inventory_file
+    target_nodes = find_targets(inventory_hash, args[:target_node_name])
+    if target_nodes.empty?
+      puts 'No targets found'
+      exit 0
+    end
+    include BoltSpec::Run
+    require 'pdk/module/build'
 
-  install_type = 'aio'
-  target = ENV['platform']
-  abs = if ENV['BEAKER_ABS'] then 'abs' else 'vmpooler' end
-  if ! target
-    STDERR.puts 'TEST_TARGET environment variable is not set'
-    STDERR.puts 'setting to default value of "centos7-64ma".'
-    target = "centos7-64ma{type=#{install_type}}"
-  end
+    module_fixture_dir = File.expand_path(File.join(File.dirname(__FILE__), 'spec', 'fixtures', 'acceptance', 'modules', 'test'))
+    module_tar = nil
+    Dir.chdir(module_fixture_dir) do
+      opts = {}
+      opts[:force] = true
+      builder = PDK::Module::Build.new(opts)
+      module_tar = builder.build
+      puts 'Built'
+      module_tar = Dir.glob('pkg/*.tar.gz').max_by { |f| File.mtime(f) }
+      raise "Unable to find package in 'pkg/*.tar.gz'" if module_tar.nil?
+      module_tar = File.expand_path(module_tar)
+    end
 
-  unless target =~ /type=/
-    puts "INFO: adding 'type=#{install_type}' to host config"
-    target += "{type=#{install_type}}"
+    target_string = if args[:target_node_name].nil?
+                      'all'
+                    else
+                      args[:target_node_name]
+                    end
+    # TODO: Currently this is Linux only
+    tmp_path = '/tmp/'
+    run_local_command("bundle exec bolt file upload #{module_tar} #{tmp_path}#{File.basename(module_tar)} --nodes #{target_string} --inventoryfile inventory.yaml")
+    install_module_command = "puppet module install #{tmp_path}#{File.basename(module_tar)}"
+    result = run_command(install_module_command, target_nodes, config: nil, inventory: inventory_hash)
+    if result.is_a?(Array)
+      result.each do |node|
+        puts "#{node['node']} failed #{node['result']}" if node['status'] != 'success'
+      end
+    else
+      raise "Failed trying to run '#{install_module_command}' against inventory."
+    end
+    puts 'Installed'
   end
 
-  cli = BeakerHostGenerator::CLI.new([target, '--hypervisor', abs])
-  nodeset_dir = 'spec/acceptance/nodesets'
-  nodeset = "#{nodeset_dir}/#{target}.yml"
-  FileUtils.mkdir_p(nodeset_dir)
-  File.open(nodeset, 'w') do |fh|
-    fh.print(cli.execute)
+  def install_remote_gem(gem_name, target_nodes, inventory_hash)
+    # TODO: Currently this is Linux only
+    install_command = "/opt/puppetlabs/puppet/bin/gem install #{gem_name}"
+    result = run_command(install_command, target_nodes, config: nil, inventory: inventory_hash)
+    if result.is_a?(Array)
+      result.each do |node|
+        puts "#{node['node']} failed #{node['result']}" if node['status'] != 'success'
+      end
+    else
+      raise "Failed trying to run '#{install_command}' against inventory."
+    end
   end
-  puts "nodeset file:"
-  puts nodeset
-  sh 'gem build puppet-strings.gemspec'
-  sh 'puppet module build spec/fixtures/acceptance/modules/test'
-  if ENV['BEAKER_keyfile']
-    sh "BEAKER_set=#{target} rspec spec/acceptance/*.rb"
-  else
-    sh "BEAKER_keyfile=$HOME/.ssh/id_rsa-acceptance BEAKER_set=#{target} rspec spec/acceptance/*.rb"
+
+  # Install the gem under test and required fixture on a collection of nodes
+  #
+  # @param :target_node_name [Array] nodes on which to install a puppet module for testing.
+  desc 'install_gems - build and install module fixtures'
+  task :install_gems, [:target_node_name] do |_task, args|
+    inventory_hash = inventory_hash_from_inventory_file
+    target_nodes = find_targets(inventory_hash, args[:target_node_name])
+    if target_nodes.empty?
+      puts 'No targets found'
+      exit 0
+    end
+    include BoltSpec::Run
+
+    # Build the gem
+    `gem build puppet-strings.gemspec --quiet`
+    result = $CHILD_STATUS
+    raise "Unable to build the puppet-strings gem. Returned exit code #{result.exitstatus}" unless result.exitstatus.zero?
+    puts 'Built'
+    # Find the gem build artifact
+    gem_tar = Dir.glob('puppet-strings-*.gem').max_by { |f| File.mtime(f) }
+    raise "Unable to find package in 'puppet-strings-*.gem'" if gem_tar.nil?
+    gem_tar = File.expand_path(gem_tar)
+
+    target_string = if args[:target_node_name].nil?
+                      'all'
+                    else
+                      args[:target_node_name]
+                    end
+    # TODO: Currently this is Linux only
+    tmp_path = '/tmp/'
+    run_local_command("bundle exec bolt file upload #{gem_tar} #{tmp_path}#{File.basename(gem_tar)} --nodes #{target_string} --inventoryfile inventory.yaml")
+
+
+    # Install dependent gems
+    install_remote_gem('yard', target_nodes, inventory_hash)
+    install_remote_gem('rgen', target_nodes, inventory_hash)
+    # Install puppet-strings
+    install_remote_gem(tmp_path + File.basename(gem_tar), target_nodes, inventory_hash)
+    puts 'Installed'
   end
 end
 
 task(:rubocop) do
   require 'rubocop'
   cli = RuboCop::CLI.new
-  cli.run(%w(-D -f s))
+  result = cli.run(%w(-D -f s))
+  abort unless result == RuboCop::CLI::STATUS_SUCCESS
 end
 
 #### CHANGELOG ####

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),

data/lib/puppet-strings/markdown.rb

@@ -5,6 +5,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'
@@ -20,6 +21,7 @@ module PuppetStrings::Markdown
     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
 

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

@@ -0,0 +1,18 @@
+require 'puppet-strings/markdown/base'
+
+module PuppetStrings::Markdown
+  # This class encapsualtes ruby data types and puppet type aliases
+  class DataType < Base
+    attr_reader :alias_of
+
+    def initialize(registry)
+      @template = 'data_type.erb'
+      super(registry, 'data type')
+      @alias_of = registry[:alias_of] unless registry[:alias_of].nil?
+    end
+
+    def render
+      super(@template)
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+require_relative 'data_type'
+
+module PuppetStrings::Markdown
+  module DataTypes
+
+    # @return [Array] list of data types
+    def self.in_dtypes
+      arr = YARD::Registry.all(:puppet_data_type).map!(&:to_hash)
+      arr.concat(YARD::Registry.all(:puppet_data_type_alias).map!(&:to_hash))
+
+      arr.sort! { |a,b| a[:name] <=> b[:name] }
+      arr.map! { |a| PuppetStrings::Markdown::DataType.new(a) }
+    end
+
+    def self.contains_private?
+      result = false
+      unless in_dtypes.nil?
+        in_dtypes.find { |type| type.private? }.nil? ? false : true
+      end
+    end
+
+    def self.render
+      final = in_dtypes.length > 0 ? "## Data types\n\n" : ""
+      in_dtypes.each do |type|
+        final << type.render unless type.private?
+      end
+      final
+    end
+
+
+    def self.toc_info
+      final = ["Data types"]
+
+      in_dtypes.each do |type|
+        final.push(type.toc_info)
+      end
+
+      final
+    end
+  end
+end