puppet-strings 0.4.0 → 0.99.0

data/spec/acceptance/emit_json_options.rb

@@ -0,0 +1,41 @@
+require 'spec_helper_acceptance'
+require 'util'
+require 'json'
+
+include PuppetStrings::Acceptance::Util
+
+describe 'Emitting JSON' do
+expected = {
+  "puppet_classes" => [],
+  "defined_types" => [],
+  "resource_types" => [],
+  "providers" => [],
+  "puppet_functions" => [
+    "name" => "function3x",
+    "file" => "/etc/puppet/modules/test/lib/puppet/parser/functions/function3x.rb",
+    "line" => 1,
+    "type" => "ruby3x",
+    "signature" => "function3x()",
+    "docstring" => {
+      "text" => "This is the function documentation for `function3x`",
+      "tags" => ["tag_name" => "return", "text" => "", "types" => ["Any"]]},
+      "source" => "Puppet::Parser::Functions.newfunction(:function3x, :doc => \"This is the function documentation for `function3x`\") do |args|\nend"
+  ]
+}
+
+  it 'should emit JSON to stdout when using the --emit-json-stdout option' do
+    test_module_path = get_test_module_path(master, /Module test/)
+    on master, puppet('strings', 'generate', '--emit-json-stdout', "#{test_module_path}/lib/puppet/parser/functions/function3x.rb") do
+      output = stdout.chomp
+      expect(JSON.parse(output)).to eq(expected)
+    end
+  end
+
+  it 'should write JSON to a file when using the --emit-json option' do
+    test_module_path = get_test_module_path(master, /Module test/)
+    tmpfile = master.tmpfile('json_output.json')
+    on master, puppet('strings', 'generate', "--emit-json #{tmpfile}", "#{test_module_path}/lib/puppet/parser/functions/function3x.rb")
+      output = read_file_on(master, tmpfile)
+      expect(JSON.parse(output)).to eq(expected)
+  end
+end

data/spec/acceptance/lib/util.rb

@@ -0,0 +1,15 @@
+module PuppetStrings
+  module Acceptance
+    module Util
+      def read_file_on(host, filename)
+        on(host, "cat #{filename}").stdout
+      end
+
+      def get_test_module_path(host, module_regex)
+        modules = JSON.parse(on(host, puppet('module', 'list', '--render-as', 'json')).stdout)
+        test_module_info = modules['modules_by_path'].values.flatten.find { |mod_info| mod_info =~ module_regex }
+        test_module_info.match(/\(([^)]*)\)/)[1]
+      end
+    end
+  end
+end

data/spec/acceptance/running_strings_generate.rb

@@ -0,0 +1,54 @@
+require 'spec_helper_acceptance'
+require 'util'
+require 'json'
+
+include PuppetStrings::Acceptance::Util
+
+describe 'Generating module documentation using generate action' do
+  before :all do
+    test_module_path = get_test_module_path(master, /Module test/)
+    on master, puppet('strings', 'generate', "#{test_module_path}/**/*.{rb,pp}")
+  end
+
+  it 'should generate documentation for manifests' do
+    expect(read_file_on(master, '/root/doc/puppet_classes/test.html')).to include('Class: test')
+  end
+
+  it 'should generate documentation for puppet functions' do
+    puppet_version = on(master, facter('puppetversion')).stdout.chomp.to_i
+
+    if puppet_version >= 4
+      html_output = read_file_on(master, '/root/doc/puppet_functions_puppet/test_3A_3Aadd.html')
+      expect(html_output).to include('Adds two integers together.')
+      expect(html_output).to include('<pre class="example code"><code>test::add(1, 2) =&gt; 3</code></pre>')
+      expect(html_output).to include('<p>The first integer to add.</p>')
+      expect(html_output).to include('<p>The second integer to add.</p>')
+      expect(html_output).to include('<p>Returns the sum of x and y.</p>')
+    end
+  end
+
+  it 'should generate documentation for 3x functions' do
+    expect(read_file_on(master, '/root/doc/puppet_functions_ruby3x/function3x.html')).to include('This is the function documentation for <code>function3x</code>')
+  end
+
+  it 'should generate documentation for 4x functions' do
+    expect(read_file_on(master, '/root/doc/puppet_functions_ruby4x/function4x.html')).to include('This is a function which is used to test puppet strings')
+  end
+
+  it 'should generate documentation for custom types' do
+    html_output = read_file_on(master, '/root/doc/puppet_types/database.html')
+    expect(html_output).to include('<p>An example server resource type.</p>')
+    expect(html_output).to include('<p>The database file to use.</p>')
+    expect(html_output).to include('<p>Documentation for a dynamic property.</p>')
+    expect(html_output).to include('<p>The database server name.</p>')
+    expect(html_output).to include('<p>Documentation for a dynamic parameter.</p>')
+    expect(html_output).to include('<p>The provider supports encryption.</p>')
+  end
+
+  it 'should generate documentation for custom providers' do
+    html_output = read_file_on(master, '/root/doc/puppet_providers_database/linux.html')
+    expect(html_output).to include('The database provider on Linux')
+    expect(html_output).to include('<tt>osfamily &mdash; linux</tt>')
+    expect(html_output).to include('<tt>database &mdash; /usr/bin/database</tt>')
+  end
+end

data/spec/fixtures/acceptance/modules/test/functions/add.pp

@@ -0,0 +1,9 @@
+# Adds two integers together.
+# @param x The first integer to add.
+# @param y The second integer to add.
+# @return [Integer] Returns the sum of x and y.
+# @example Example of adding two integers.
+#   test::add(1, 2) => 3
+function test::add(Integer $x, Integer $y) {
+  $x + $y
+}

data/spec/fixtures/acceptance/modules/test/lib/puppet/functions/4x_function.rb

@@ -0,0 +1,5 @@
+# function 4x
+#
+# This is a function which is used to test puppet strings
+Puppet::Functions.create_function(:function4x) do
+end

data/spec/fixtures/acceptance/modules/test/lib/puppet/parser/functions/function3x.rb

@@ -0,0 +1,2 @@
+Puppet::Parser::Functions.newfunction(:function3x, :doc => "This is the function documentation for `function3x`") do |args|
+end

data/spec/fixtures/acceptance/modules/test/lib/puppet/provider/server/linux.rb

@@ -0,0 +1,9 @@
+Puppet::Type.type(:database).provide :linux do
+  confine 'osfamily' => 'linux'
+  defaultfor 'osfamily' => 'linux'
+  commands :database => '/usr/bin/database'
+
+  desc 'The database provider on Linux.'
+
+  # ...
+end

data/spec/fixtures/acceptance/modules/test/lib/puppet/type/database.rb

@@ -0,0 +1,15 @@
+# @!puppet.type.param [value1, value2, value3] my_param Documentation for a dynamic parameter.
+# @!puppet.type.property [foo, bar, baz] my_prop Documentation for a dynamic property.
+Puppet::Type.newtype(:database) do
+  desc 'An example server resource type.'
+  feature :encryption, 'The provider supports encryption.', methods: [:encrypt]
+
+  newparam(:address) do
+    isnamevar
+    desc 'The database server name.'
+  end
+
+  newproperty(:file) do
+    desc 'The database file to use.'
+  end
+end

data/spec/fixtures/acceptance/modules/test/manifests/init.pp

@@ -0,0 +1,27 @@
+# Class: test
+#
+#   This class exists to serve as fixture data for testing the puppet strings face
+#
+# @example
+#   class { "test": }
+#
+# @param package_name The name of the package
+# @param service_name The name of the service
+class test (
+  $package_name = $test::params::package_name,
+  $service_name = $test::params::service_name,
+
+) inherits test::params {
+
+  # validate parameters here
+
+  class { 'test::install': } ->
+  class { 'test::config': } ~>
+  class { 'test::service': } ->
+  Class['test']
+
+  File {
+    owner => 'user',
+    path => 'some/file/path',
+  }
+}

data/spec/fixtures/acceptance/modules/test/manifests/triple_nested_classes.pp

@@ -0,0 +1,27 @@
+# Testing tested classes
+# docs stuff
+# @param nameservers [String] Don't ask me what this does!
+# @param default_lease_time [Integer[1024, 8192]] text goes here
+# @param max_lease_time does stuff
+class outer (
+		$dnsdomain,
+		$nameservers,
+		$default_lease_time = 3600,
+		$max_lease_time     = 86400
+		) {
+	# @param options [String[5,7]] gives user choices
+	# @param multicast [Boolean] foobar
+	# @param servers yep, that's right
+	class middle (
+      $options   = "iburst",
+      $servers,
+      $multicast = false
+    ) {
+    class inner (
+        $choices   = "uburst",
+        $secenekler   = "weallburst",
+        $boxen,
+        $manyspell = true
+      ) {}
+    }
+}

data/spec/fixtures/acceptance/modules/test/metadata.json

@@ -0,0 +1,6 @@
+{
+  "name": "username-test",
+  "version": "0.0.1",
+  "author": "username",
+  "license": "Apache 2.0"
+}

data/spec/fixtures/unit/json/output.json

@@ -0,0 +1,348 @@
+{
+  "puppet_classes": [
+    {
+      "name": "klass",
+      "file": "(stdin)",
+      "line": 5,
+      "inherits": "foo::bar",
+      "docstring": {
+        "text": "A simple class.",
+        "tags": [
+          {
+            "tag_name": "param",
+            "text": "First param.",
+            "types": [
+              "Integer"
+            ],
+            "name": "param1"
+          },
+          {
+            "tag_name": "param",
+            "text": "Second param.",
+            "types": [
+              "Any"
+            ],
+            "name": "param2"
+          },
+          {
+            "tag_name": "param",
+            "text": "Third param.",
+            "types": [
+              "String"
+            ],
+            "name": "param3"
+          }
+        ]
+      },
+      "defaults": {
+        "param3": "hi"
+      },
+      "source": "class klass(Integer $param1, $param2, String $param3 = hi) inherits foo::bar {\n}"
+    }
+  ],
+  "defined_types": [
+    {
+      "name": "dt",
+      "file": "(stdin)",
+      "line": 12,
+      "docstring": {
+        "text": "A simple defined type.",
+        "tags": [
+          {
+            "tag_name": "param",
+            "text": "First param.",
+            "types": [
+              "Integer"
+            ],
+            "name": "param1"
+          },
+          {
+            "tag_name": "param",
+            "text": "Second param.",
+            "types": [
+              "Any"
+            ],
+            "name": "param2"
+          },
+          {
+            "tag_name": "param",
+            "text": "Third param.",
+            "types": [
+              "String"
+            ],
+            "name": "param3"
+          }
+        ]
+      },
+      "defaults": {
+        "param3": "hi"
+      },
+      "source": "define dt(Integer $param1, $param2, String $param3 = hi) {\n}"
+    }
+  ],
+  "resource_types": [
+    {
+      "name": "database",
+      "file": "(stdin)",
+      "line": 43,
+      "docstring": {
+        "text": "An example database server resource type."
+      },
+      "properties": [
+        {
+          "name": "ensure",
+          "description": "What state the database should be in.",
+          "values": [
+            "present",
+            "absent",
+            "up",
+            "down"
+          ],
+          "aliases": {
+            "up": "present",
+            "down": "absent"
+          },
+          "default": "up"
+        },
+        {
+          "name": "file",
+          "description": "The database file to use."
+        },
+        {
+          "name": "log_level",
+          "description": "The log level to use.",
+          "values": [
+            "debug",
+            "warn",
+            "error"
+          ],
+          "default": "warn"
+        }
+      ],
+      "parameters": [
+        {
+          "name": "address",
+          "description": "The database server name.",
+          "isnamevar": true
+        },
+        {
+          "name": "encryption_key",
+          "description": "The encryption key to use."
+        },
+        {
+          "name": "encrypt",
+          "description": "Whether or not to encrypt the database.",
+          "values": [
+            "true",
+            "false",
+            "yes",
+            "no"
+          ],
+          "default": "false"
+        }
+      ],
+      "features": [
+        {
+          "name": "encryption",
+          "description": "The provider supports encryption."
+        }
+      ]
+    }
+  ],
+  "providers": [
+    {
+      "name": "linux",
+      "type_name": "database",
+      "file": "(stdin)",
+      "line": 33,
+      "docstring": {
+        "text": "An example provider on Linux."
+      },
+      "confines": {
+        "kernel": "Linux",
+        "osfamily": "RedHat"
+      },
+      "features": [
+        "implements_some_feature",
+        "some_other_feature"
+      ],
+      "defaults": {
+        "kernel": "Linux"
+      },
+      "commands": {
+        "foo": "/usr/bin/foo"
+      }
+    }
+  ],
+  "puppet_functions": [
+    {
+      "name": "func",
+      "file": "(stdin)",
+      "line": 6,
+      "type": "puppet",
+      "signature": "func(Integer $param1, Any $param2, String $param3 = hi)",
+      "docstring": {
+        "text": "A simple function.",
+        "tags": [
+          {
+            "tag_name": "param",
+            "text": "First param.",
+            "types": [
+              "Integer"
+            ],
+            "name": "param1"
+          },
+          {
+            "tag_name": "param",
+            "text": "Second param.",
+            "types": [
+              "Any"
+            ],
+            "name": "param2"
+          },
+          {
+            "tag_name": "param",
+            "text": "Third param.",
+            "types": [
+              "String"
+            ],
+            "name": "param3"
+          },
+          {
+            "tag_name": "return",
+            "text": "Returns nothing.",
+            "types": [
+              "Undef"
+            ]
+          }
+        ]
+      },
+      "defaults": {
+        "param3": "hi"
+      },
+      "source": "function func(Integer $param1, $param2, String $param3 = hi) {\n}"
+    },
+    {
+      "name": "func3x",
+      "file": "(stdin)",
+      "line": 1,
+      "type": "ruby3x",
+      "signature": "func3x(String $first, Any $second)",
+      "docstring": {
+        "text": "An example 3.x function.",
+        "tags": [
+          {
+            "tag_name": "param",
+            "text": "The first parameter.",
+            "types": [
+              "String"
+            ],
+            "name": "first"
+          },
+          {
+            "tag_name": "param",
+            "text": "The second parameter.",
+            "types": [
+              "Any"
+            ],
+            "name": "second"
+          },
+          {
+            "tag_name": "return",
+            "text": "Returns nothing.",
+            "types": [
+              "Undef"
+            ]
+          }
+        ]
+      },
+      "source": "Puppet::Parser::Functions.newfunction(:func3x, doc: <<-DOC\nAn example 3.x function.\n@param [String] first The first parameter.\n@param second The second parameter.\n@return [Undef] Returns nothing.\nDOC\n) do |*args|\nend"
+    },
+    {
+      "name": "func4x",
+      "file": "(stdin)",
+      "line": 11,
+      "type": "ruby4x",
+      "docstring": {
+        "text": "An example 4.x function.",
+        "tags": [
+          {
+            "tag_name": "overload",
+            "signature": "func4x(Integer $param1, Any $param2, Optional[Array[String]] $param3)",
+            "docstring": {
+              "text": "The first overload.",
+              "tags": [
+                {
+                  "tag_name": "param",
+                  "text": "The first parameter.",
+                  "types": [
+                    "Integer"
+                  ],
+                  "name": "param1"
+                },
+                {
+                  "tag_name": "param",
+                  "text": "The second parameter.",
+                  "types": [
+                    "Any"
+                  ],
+                  "name": "param2"
+                },
+                {
+                  "tag_name": "param",
+                  "text": "The third parameter.",
+                  "types": [
+                    "Optional[Array[String]]"
+                  ],
+                  "name": "param3"
+                },
+                {
+                  "tag_name": "return",
+                  "text": "Returns nothing.",
+                  "types": [
+                    "Undef"
+                  ]
+                }
+              ]
+            },
+            "name": "func4x"
+          },
+          {
+            "tag_name": "overload",
+            "signature": "func4x(Boolean $param, Callable &$block)",
+            "docstring": {
+              "text": "The second overload.",
+              "tags": [
+                {
+                  "tag_name": "param",
+                  "text": "The first parameter.",
+                  "types": [
+                    "Boolean"
+                  ],
+                  "name": "param"
+                },
+                {
+                  "tag_name": "param",
+                  "text": "The block parameter.",
+                  "types": [
+                    "Callable"
+                  ],
+                  "name": "&block"
+                },
+                {
+                  "tag_name": "return",
+                  "text": "Returns a string.",
+                  "types": [
+                    "String"
+                  ]
+                }
+              ]
+            },
+            "name": "func4x"
+          }
+        ]
+      },
+      "source": "Puppet::Functions.create_function(:func4x) do\n  # The first overload.\n  # @param param1 The first parameter.\n  # @param param2 The second parameter.\n  # @param param3 The third parameter.\n  # @return [Undef] Returns nothing.\n  dispatch :foo do\n    param          'Integer',       :param1\n    param          'Any',           :param2\n    optional_param 'Array[String]', :param3\n  end\n\n  # The second overload.\n  # @param param The first parameter.\n  # @param block The block parameter.\n  # @return [String] Returns a string.\n  dispatch :other do\n    param 'Boolean', :param\n    block_param\n  end\nend"
+    }
+  ]
+}