puppet-strings 1.2.1 → 2.0.0

data/lib/puppet-strings/yard/templates/default/puppet_plan/html/box_info.erb

@@ -0,0 +1,10 @@
+<div class="box_info">
+  <dl>
+    <dt>Defined in:</dt>
+    <dd>
+      <%= object.file %><% if object.files.size > 1 %><span class="defines">,<br />
+      <%= object.files[1..-1].map {|f| f.first }.join(",<br /> ") %></div>
+      <% end %>
+    </dd>
+  </dl>
+</div>

data/lib/puppet-strings/yard/templates/default/puppet_plan/html/header.erb

@@ -0,0 +1 @@
+<h1>Puppet Plan: <%= object.name %></h1>

data/lib/puppet-strings/yard/templates/default/puppet_plan/html/overview.erb

@@ -0,0 +1,6 @@
+<h2>Overview</h2>
+<div class="docstring">
+  <div class="discussion">
+    <%= htmlify(object.docstring) %>
+  </div>
+</div>

data/lib/puppet-strings/yard/templates/default/puppet_plan/html/setup.rb

@@ -0,0 +1,11 @@
+# Initializes the template.
+# @return [void]
+def init
+  sections :header, :box_info, :summary, :overview, T('tags'), :source
+end
+
+# Renders the box_info section.
+# @return [String] Returns the rendered section.
+def box_info
+  erb(:box_info)
+end

data/lib/puppet-strings/yard/templates/default/puppet_plan/html/source.erb

@@ -0,0 +1,12 @@
+<div class="method_details_list">
+  <table class="source_code">
+    <tr>
+      <td>
+        <pre class="lines"><%= "\n\n\n" %><%= h format_lines(object) %></pre>
+      </td>
+      <td>
+        <pre class="code"><span class="info file"># File '<%= h object.file %>'<% if object.line %>, line <%= object.line %><% end %></span><%= "\n\n" %><%= html_syntax_highlight object.source %></pre>
+      </td>
+    </tr>
+  </table>
+</div>

data/lib/puppet-strings/yard/templates/default/puppet_plan/html/summary.erb

@@ -0,0 +1,4 @@
+<% if object.docstring.has_tag?(:summary) %>
+  <h2>Summary</h2>
+  <%= object.docstring.tag(:summary).text %>
+<% end %>

data/lib/puppet-strings/yard/templates/default/puppet_task/html/box_info.erb

@@ -0,0 +1,9 @@
+<div class="box_info">
+  <dl>
+    <dt>Defined in:</dt>
+    <dd>
+      <%= object.file %>,<br />
+      <%= object.file.gsub('json','rb') %><br/></div>
+    </dd>
+  </dl>
+</div>

data/lib/puppet-strings/yard/templates/default/puppet_task/html/header.erb

@@ -0,0 +1 @@
+<h1>Puppet Task: <%= object.name %></h1>

data/lib/puppet-strings/yard/templates/default/puppet_task/html/input.erb

@@ -0,0 +1,5 @@
+<% if json['input_method'] || json['supports_noop'] %>
+<div class="tags">
+    <p><strong>Supports noop?</strong> <%= json['supports_noop'] ? "true" : "false" %></p>
+</div>
+<% end %>

data/lib/puppet-strings/yard/templates/default/puppet_task/html/overview.erb

@@ -0,0 +1,6 @@
+<h2>Overview</h2>
+<div class="docstring">
+  <div class="discussion">
+    <%= description %>
+  </div>
+</div>

data/lib/puppet-strings/yard/templates/default/puppet_task/html/parameters.erb

@@ -0,0 +1,16 @@
+<% if @parameters && !@parameters.empty? %>
+<div class="tags">
+  <p class="tag_title"><%= @tag_title %></p>
+  <ul>
+    <% @parameters.each do |parameter, values| %>
+    <li>
+        <span class="name"><%= parameter %></span>
+        <span class="type">
+            <tt>(<%= values['type'] %>)</tt>
+        </span>
+        <% if values['description'] %> &mdash; <%= values['description'] %><% end %>
+    </li>
+    <% end %>
+  </ul>
+</div>
+<% end %>

data/lib/puppet-strings/yard/templates/default/puppet_task/html/setup.rb

@@ -0,0 +1,22 @@
+# Initializes the template.
+# @return [void]
+def init
+  sections :header, :box_info, T('tags'), :overview, :input, :parameters
+end
+
+def json
+  object.statement.json
+end
+
+def description
+  json['description']
+end
+
+# Renders the parameters section.
+# @return [String] Returns the rendered section.
+def parameters
+  @parameters = json['parameters'] || []
+  @parameters.to_a.sort!
+  @tag_title = 'Parameters'
+  erb(:parameters)
+end

data/lib/puppet-strings/yard/templates/default/puppet_task/html/supports_noop.erb

@@ -0,0 +1,3 @@
+<% if json['supports_noop'] %>
+<strong>Supports noop?</strong> <%= json['supports_noop'] %>
+<% end %>

data/lib/puppet-strings/yard/templates/default/tags/setup.rb

@@ -5,7 +5,9 @@ def param
     object.type == :method ||
     object.type == :puppet_class ||
     object.type == :puppet_defined_type ||
-    object.type == :puppet_function
+    object.type == :puppet_function ||
+    object.type == :puppet_task ||
+    object.type == :puppet_plan
 end
 
 # Renders the overload section.

data/lib/puppet-strings/yard/util.rb

@@ -14,4 +14,18 @@ module PuppetStrings::Yard::Util
 
     Puppet::Util::Docs.scrub(str)
   end
+
+  # hacksville, usa
+  # YARD creates ids in the html with with the style of "label-Module+description", where the markdown
+  # we use in the README involves the GitHub-style, which is #module-description. This takes our GitHub-style
+  # links and converts them to reference the YARD-style ids.
+  # @see https://github.com/octokit/octokit.rb/blob/0f13944e8dbb0210d1e266addd3335c6dc9fe36a/yard/default/layout/html/setup.rb#L5-L14
+  # @param [String] data HTML document to convert
+  # @return [String] HTML document with links converted
+  def self.github_to_yard_links(data)
+    data.scan(/href\=\"\#(.+)\"/).each do |bad_link|
+      data.gsub!("=\"##{bad_link.first}\"", "=\"#label-#{bad_link.first.capitalize.gsub('-', '+')}\"")
+    end
+    data
+  end
 end

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

@@ -598,5 +598,55 @@
       },
       "source": "Puppet::Functions.create_function(:func4x_1) do\n  # @param param1 The first parameter.\n  # @return [Undef] Returns nothing.\n  dispatch :foobarbaz do\n    param          'Integer',       :param1\n  end\nend"
     }
+  ],
+  "puppet_tasks": [
+    {
+      "name": "(stdin)",
+      "file": "(stdin)",
+      "line": 0,
+      "docstring": {
+        "text": "Allows you to backup your database to local file.",
+        "tags": [
+          {
+            "name": "database",
+            "tag_name": "param",
+            "text": "Database to connect to",
+            "types": [
+              "Optional[String[1]]"
+            ]
+          },
+          {
+            "name": "user",
+            "tag_name": "param",
+            "text": "The user",
+            "types": [
+              "Optional[String[1]]"
+            ]
+          },
+          {
+            "name": "password",
+            "tag_name": "param",
+            "text": "The password",
+            "types": [
+              "Optional[String[1]]"
+            ]
+          },
+          {
+            "name": "sql",
+            "tag_name": "param",
+            "text": "Path to file you want backup to",
+            "types": [
+              "String[1]"
+            ]
+          }
+        ]
+      },
+      "source": "{\n  \"description\": \"Allows you to backup your database to local file.\",\n  \"input_method\": \"stdin\",\n  \"parameters\": {\n    \"database\": {\n      \"description\": \"Database to connect to\",\n      \"type\": \"Optional[String[1]]\"\n    },\n    \"user\": {\n      \"description\": \"The user\",\n      \"type\": \"Optional[String[1]]\"\n    },\n    \"password\": {\n      \"description\": \"The password\",\n      \"type\": \"Optional[String[1]]\"\n    },\n     \"sql\": {\n      \"description\": \"Path to file you want backup to\",\n      \"type\": \"String[1]\"\n    }\n  }\n}\n",
+      "supports_noop": false,
+      "input_method": "stdin"
+    }
+  ],
+  "puppet_plans": [
+
   ]
 }

data/spec/fixtures/unit/json/output_with_plan.json

@@ -0,0 +1,689 @@
+{
+  "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": "apt_key",
+      "file": "(stdin)",
+      "line": 92,
+      "docstring": {
+        "text": "This type provides Puppet with the capabilities to manage GPG keys needed\nby apt to perform package validation. Apt has it's own GPG keyring that can\nbe manipulated through the `apt-key` command.\n**Autorequires**:\nIf Puppet is given the location of a key file which looks like an absolute\npath this type will autorequire that file.",
+        "tags": [
+          {
+            "tag_name": "summary",
+            "text": "Example resource type using the new API."
+          },
+          {
+            "tag_name": "raise",
+            "text": "SomeError"
+          },
+          {
+            "tag_name": "example",
+            "text": "apt_key { '6F6B15509CF8E59E6E469F327F438280EF8D349F':\n  source => 'http://apt.puppetlabs.com/pubkey.gpg'\n}",
+            "name": "here's an example"
+          }
+        ]
+      },
+      "properties": [
+        {
+          "name": "ensure",
+          "description": "Whether this apt key should be present or absent on the target system.",
+          "data_type": "Enum[present, absent]"
+        },
+        {
+          "name": "created",
+          "description": "Date the key was created, in ISO format.",
+          "data_type": "String"
+        }
+      ],
+      "parameters": [
+        {
+          "name": "id",
+          "description": "The ID of the key you want to manage.",
+          "data_type": "Variant[Pattern[/A(0x)?[0-9a-fA-F]{8}Z/], Pattern[/A(0x)?[0-9a-fA-F]{16}Z/], Pattern[/A(0x)?[0-9a-fA-F]{40}Z/]]",
+          "isnamevar": true
+        }
+      ]
+    },
+    {
+      "name": "database",
+      "file": "(stdin)",
+      "line": 54,
+      "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": 43,
+      "docstring": {
+        "text": "An example provider on Linux."
+      },
+      "confines": {
+        "kernel": "Linux",
+        "osfamily": "RedHat"
+      },
+      "features": [
+        "implements_some_feature",
+        "some_other_feature"
+      ],
+      "defaults": [
+        [
+          [
+            "kernel",
+            "Linux"
+          ]
+        ],
+        [
+          [
+            "osfamily",
+            "RedHat"
+          ],
+          [
+            "operatingsystemmajrelease",
+            "7"
+          ]
+        ]
+      ],
+      "commands": {
+        "foo": "/usr/bin/foo"
+      }
+    }
+  ],
+  "puppet_functions": [
+    {
+      "name": "func",
+      "file": "(stdin)",
+      "line": 6,
+      "type": "puppet",
+      "signatures": [
+        {
+          "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"
+                ]
+              }
+            ]
+          }
+        }
+      ],
+      "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",
+      "signatures": [
+        {
+          "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"
+                ]
+              }
+            ]
+          }
+        }
+      ],
+      "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",
+      "signatures": [
+        {
+          "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"
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "signature": "func4x(Boolean $param, Callable &$block)",
+          "docstring": {
+            "text": "",
+            "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"
+                ]
+              }
+            ]
+          }
+        }
+      ],
+      "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": "",
+              "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 Returns nothing.\n  dispatch :foo do\n    param          'Integer',       :param1\n    param          'Any',           :param2\n    optional_param 'Array[String]', :param3\n    return_type 'Undef'\n  end\n\n  # @param param The first parameter.\n  # @param block The block parameter.\n  # @return Returns a string.\n  dispatch :other do\n    param 'Boolean', :param\n    block_param\n    return_type 'String'\n  end\nend"
+    },
+    {
+      "name": "func4x_1",
+      "file": "(stdin)",
+      "line": 35,
+      "type": "ruby4x",
+      "signatures": [
+        {
+          "signature": "func4x_1(Integer $param1)",
+          "docstring": {
+            "text": "An example 4.x function with only one signature.",
+            "tags": [
+              {
+                "tag_name": "param",
+                "text": "The first parameter.",
+                "types": [
+                  "Integer"
+                ],
+                "name": "param1"
+              },
+              {
+                "tag_name": "return",
+                "text": "Returns nothing.",
+                "types": [
+                  "Undef"
+                ]
+              }
+            ]
+          }
+        }
+      ],
+      "docstring": {
+        "text": "An example 4.x function with only one signature.",
+        "tags": [
+          {
+            "tag_name": "param",
+            "text": "The first parameter.",
+            "types": [
+              "Integer"
+            ],
+            "name": "param1"
+          },
+          {
+            "tag_name": "return",
+            "text": "Returns nothing.",
+            "types": [
+              "Undef"
+            ]
+          }
+        ]
+      },
+      "source": "Puppet::Functions.create_function(:func4x_1) do\n  # @param param1 The first parameter.\n  # @return [Undef] Returns nothing.\n  dispatch :foobarbaz do\n    param          'Integer',       :param1\n  end\nend"
+    }
+  ],
+  "puppet_tasks": [
+    {
+      "name": "(stdin)",
+      "file": "(stdin)",
+      "line": 0,
+      "docstring": {
+        "text": "Allows you to backup your database to local file.",
+        "tags": [
+          {
+            "name": "database",
+            "tag_name": "param",
+            "text": "Database to connect to",
+            "types": [
+              "Optional[String[1]]"
+            ]
+          },
+          {
+            "name": "user",
+            "tag_name": "param",
+            "text": "The user",
+            "types": [
+              "Optional[String[1]]"
+            ]
+          },
+          {
+            "name": "password",
+            "tag_name": "param",
+            "text": "The password",
+            "types": [
+              "Optional[String[1]]"
+            ]
+          },
+          {
+            "name": "sql",
+            "tag_name": "param",
+            "text": "Path to file you want backup to",
+            "types": [
+              "String[1]"
+            ]
+          }
+        ]
+      },
+      "source": "{\n  \"description\": \"Allows you to backup your database to local file.\",\n  \"input_method\": \"stdin\",\n  \"parameters\": {\n    \"database\": {\n      \"description\": \"Database to connect to\",\n      \"type\": \"Optional[String[1]]\"\n    },\n    \"user\": {\n      \"description\": \"The user\",\n      \"type\": \"Optional[String[1]]\"\n    },\n    \"password\": {\n      \"description\": \"The password\",\n      \"type\": \"Optional[String[1]]\"\n    },\n     \"sql\": {\n      \"description\": \"Path to file you want backup to\",\n      \"type\": \"String[1]\"\n    }\n  }\n}\n",
+      "supports_noop": false,
+      "input_method": "stdin"
+    }
+  ],
+  "puppet_plans": [
+    {
+      "name": "plann",
+      "file": "(stdin)",
+      "line": 5,
+      "docstring": {
+        "text": "A simple plan.",
+        "tags": [
+          {
+            "tag_name": "param",
+            "text": "First param.",
+            "types": [
+              "String"
+            ],
+            "name": "param1"
+          },
+          {
+            "tag_name": "param",
+            "text": "Second param.",
+            "types": [
+              "Any"
+            ],
+            "name": "param2"
+          },
+          {
+            "tag_name": "param",
+            "text": "Third param.",
+            "types": [
+              "Integer"
+            ],
+            "name": "param3"
+          }
+        ]
+      },
+      "defaults": {
+        "param3": "1"
+      },
+      "source": "plan plann(String $param1, $param2, Integer $param3 = 1) {\n}"
+    }
+  ]
+}