puppet-strings 1.1.1 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 617d17b2ad3472b75cc4710c3041ff341f32f908
-  data.tar.gz: b79393ed1448e9a68e870b1c7c26e5e1e0fa7cd3
+  metadata.gz: e0b022bc727dcda3a4a796595059fa42a79815f2
+  data.tar.gz: 00aebdc79f8e40a6149940a6e495e2cf3b2e356d
 SHA512:
-  metadata.gz: fd878646dc1c5daa2d95cd60a8ee63ca1550862ee1cfefe333a826ba452b6ed5962460f49717cb754ee734b8a8a2aeab1a88b752b49ed358c05043da552ae6d6
-  data.tar.gz: 4991c269e0354a10b447078f8714627c034b00bcbdc8db0a1d99243e9f1108fdb7a1367540abe79405a3d1ac255f1d6f16d461b0819f4abe8f47cf877a8d5e42
+  metadata.gz: c52b785c39bf5e539934a64aea7af0b9f1fe192f0caf6eb327e6c43926d1a9d943ef1ec4c1dec30ebacd779d2694d8bf8f55fc90472f37beb9d7d3dc15b84b3d
+  data.tar.gz: 89ee514938a2f69a69705c79b52598e5b9144a984dcf7ab6a5304dfab6a372fc3686b548936517cd135f7dc8ea13b8ef1951ebb1f430e6dab740384a5f26a191

data/CHANGELOG.md

@@ -1,3 +1,21 @@
+# Change log
+
+All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](http://semver.org).
+
+## [1.2.0](https://github.com/puppetlabs/puppet-strings/tree/1.2.0) (2018-02-26)
+
+[Full Changelog](https://github.com/puppetlabs/puppet-strings/compare/1.1.1...1.2.0)
+
+### Added
+
+- \(PDOC-184\) generate markdown [\#156](https://github.com/puppetlabs/puppet-strings/pull/156) ([eputnam](https://github.com/eputnam))
+- \(PDK-437\) Add support for Resource API types [\#153](https://github.com/puppetlabs/puppet-strings/pull/153) ([DavidS](https://github.com/DavidS))
+
+### Fixed
+
+- Fix return type matching for Puppet functions [\#159](https://github.com/puppetlabs/puppet-strings/pull/159) ([pegasd](https://github.com/pegasd))
+- Add rgen as a runtime dependency [\#149](https://github.com/puppetlabs/puppet-strings/pull/149) ([rnelson0](https://github.com/rnelson0))
+
 ## 2017-10-20 - Release 1.1.1
 
 ### BugFixes
@@ -166,3 +184,6 @@ All related tickets can be found under the [PDOC][PDOC JIRA] JIRA project with t
 - Puppet namespaces are no longer mangled for nested classes and defined types **(PDOC-25)**
 - Strings is now compatible with the renaming of the Puppetx/puppetx namespace to PuppetX/puppet_x **(PDOC-26)**
 - 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)*

data/Gemfile

@@ -4,7 +4,7 @@ gemspec
 
 gem 'rgen'
 gem 'redcarpet'
-gem 'yard', '0.9.5'
+gem 'yard', '~> 0.9.11'
 
 if ENV['PUPPET_GEM_VERSION']
   gem 'puppet', ENV['PUPPET_GEM_VERSION'], :require => false
@@ -13,10 +13,12 @@ else
 end
 
 group :test do
-  gem "rspec", "~> 3.1"
+  gem 'codecov'
   gem 'mocha'
   gem 'puppetlabs_spec_helper'
   gem 'serverspec'
+  gem 'simplecov-console'
+  gem "rspec", "~> 3.1"
 end
 
 group :acceptance do

data/README.md

@@ -162,17 +162,33 @@ Strings can produce documentation in JSON and then either generate a `.json` fil
 To generate JSON documentation to a file, run:
 
 ```
-$ puppet strings generate --emit-json documentation.json
+$ puppet strings generate --format json --out documentation.json
 ```
 
 To generate and then print JSON documentation to stdout, run:
 
 ```
-$ puppet strings generate --emit-json-stdout
+$ puppet strings generate --format json
 ```
 
 For details about Strings JSON output, see [Strings JSON schema](https://github.com/puppetlabs/puppet-strings/blob/master/JSON.md).
 
+### Output documents in Markdown
+
+Strings can also produce documentation in Markdown and then either generate an `.md` file or print Markdown to stdout. The generated markdown layout has been reviewed and approved by Puppet's tech pubs team and is the same that is used in Puppet Supported modules.
+
+To generate REFERENCE.md:
+
+```
+$ puppet strings generate --format markdown
+```
+
+To write Markdown documentation to another file, use the --out option:
+
+```
+$ puppet strings generate --format markdown --out docs/INFO.md
+```
+
 ### Output documents to GitHub Pages
 
 To generate documents and then make them available on [GitHub Pages](https://pages.github.com/), use the Strings rake task `strings:gh_pages:update`. See [Rake tasks](#rake-tasks) for setup and usage details.
@@ -196,7 +212,7 @@ To document Puppet classes and defined types, use a series of comments to create
 #   include example
 #
 # @param first The first parameter for this class
-# @param second The second paramter for this class
+# @param second The second parameter for this class
 class example_class(
   String $first  = $example::params::first_arg,
   Integer $second = $example::params::second_arg,
@@ -285,6 +301,35 @@ end
 
 All provider method calls, including `confine`, `defaultfor`, and `commands`, are automatically parsed and documented by Strings. The `desc` method is used to generate the docstring, and can include tags such as `@example` if written as a heredoc.
 
+Document types that use the new [Resource API](https://github.com/puppetlabs/puppet-resource_api):
+
+```ruby
+Puppet::ResourceApi.register_type(
+  name: 'database',
+  docs: 'An example database server resource type.',
+  attributes: {
+    ensure: {
+      type: 'Enum[present, absent, up, down]',
+      desc: 'What state the database should be in.',
+      default: 'up',
+    },
+    address: {
+      type: 'String',
+      desc: 'The database server name.',
+      behaviour: :namevar,
+    },
+    encrypt: {
+      type: 'Boolean',
+      desc: 'Whether or not to encrypt the database.',
+      default: false,
+      behaviour: :parameter,
+    },
+  },
+)
+```
+
+Here, the `docs` key acts like the `desc` method of the traditional resource type. Everything else is the same, except that now everything is a value in the data structure, not passed to methods.
+
 **Note**: Puppet Strings can not evaluate your Ruby code, so only certain static expressions are supported.
 
 ### Documenting functions
@@ -418,17 +463,15 @@ function example(string $name) {
 
 ### Available Strings tags
 
-The most commonly used tags for Strings are:
-
-* `@param`: Documents a parameter with a given name, type and optional description.
-* `@return`: Describes the return value (and type or types) of a method. You can list multiple return tags for a method if the method has distinct return cases. In this case, begin each case with "if".
+* `@api`: Describes the resource as private or public, most commonly used with classes or defined types.
 * `@example`: Shows an example snippet of code for an object. The first line is an optional title. See above for more about how to [include examples in documentation](#including-examples-in-documentation).
+* `@param`: Documents a parameter with a given name, type and optional description.
 * `@!puppet.type.param`: Documents dynamic type parameters. See [Documenting resource types and providers](#documenting-resource-types-and-providers) above.
 * `@!puppet.type.property`: Documents dynamic type properties. See [Documenting resource types and providers](#documenting-resource-types-and-providers) above.
-* `@since`: Lists the version in which the object was first added.
+* `@return`: Describes the return value (and type or types) of a method. You can list multiple return tags for a method if the method has distinct return cases. In this case, begin each case with "if".
 * `@see`: Adds "see also" references. Accepts URLs or other code objects with an optional description at the end. Note that the URL or object is automatically linked by YARD and does not need markup formatting.
-
-For a complete list of tags, see the [YARD Tags Overview](http://www.rubydoc.info/gems/yard/file/docs/Tags.md).
+* `@since`: Lists the version in which the object was first added.
+* `@summary`: A short description of the documented item.
 
 ### Rake tasks
 

data/codecov.yml

@@ -0,0 +1,3 @@
+---
+# disable comments, info can be gotten from the pr status updates, and the comment editing spams the hipchat notifications
+comment: false

data/lib/puppet-strings.rb

@@ -14,7 +14,9 @@ module PuppetStrings
   # @option options [Boolean] :debug Enable YARD debug output.
   # @option options [Boolean] :backtrace Enable YARD backtraces.
   # @option options [String] :markup The YARD markup format to use (defaults to 'markdown').
-  # @option options [String] :json Enables JSON output to the given file. If the file is nil, STDOUT is used.
+  # @option options [String] :path Write the selected format to a file path
+  # @option options [Boolean] :markdown From the --format option, is the format Markdown?
+  # @option options [Boolean] :json Is the format JSON?
   # @option options [Array<String>] :yard_args The arguments to pass to yard.
   # @return [void]
   def self.generate(search_patterns = DEFAULT_SEARCH_PATTERNS, options = {})
@@ -27,15 +29,18 @@ module PuppetStrings
     args << '--backtrace' if options[:backtrace]
     args << "-m#{options[:markup] || 'markdown'}"
 
-    render_as_json = options.key? :json
-    json_file = nil
-    if render_as_json
-      json_file = options[:json]
+    file = nil
+    if options[:json] || options[:markdown]
+      file = if options[:json]
+               options[:path]
+             elsif options[:markdown]
+               options[:path] || "REFERENCE.md"
+             end
       # Disable output and prevent stats/progress when writing to STDOUT
       args << '-n'
-      args << '-q' unless json_file
-      args << '--no-stats' unless json_file
-      args << '--no-progress' unless json_file
+      args << '-q' unless file
+      args << '--no-stats' unless file
+      args << '--no-progress' unless file
     end
 
     yard_args = options[:yard_args]
@@ -46,10 +51,24 @@ module PuppetStrings
     YARD::CLI::Yardoc.run(*args)
 
     # If outputting JSON, render the output
-    if render_as_json
-      require 'puppet-strings/json'
-      PuppetStrings::Json.render(json_file)
+    if options[:json]
+      render_json(file)
     end
+
+    # If outputting Markdown, render the output
+    if options[:markdown]
+      render_markdown(file)
+    end
+  end
+
+  def self.render_json(path)
+    require 'puppet-strings/json'
+    PuppetStrings::Json.render(path)
+  end
+
+  def self.render_markdown(path)
+    require 'puppet-strings/markdown'
+    PuppetStrings::Markdown.render(path)
   end
 
   # Runs the YARD documentation server.

data/lib/puppet-strings/json.rb

@@ -34,6 +34,13 @@ module PuppetStrings::Json
       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

data/lib/puppet-strings/markdown.rb

@@ -0,0 +1,35 @@
+require 'puppet-strings/json'
+
+# module for parsing Yard Registries and generating markdown
+module PuppetStrings::Markdown
+  require_relative 'markdown/puppet_classes'
+  require_relative 'markdown/functions'
+  require_relative 'markdown/defined_types'
+  require_relative 'markdown/resource_types'
+  require_relative 'markdown/table_of_contents'
+
+  # generates markdown documentation
+  # @return [String] markdown doc
+  def self.generate
+    final = "# Reference\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
+  end
+
+  # mimicks the behavior of the json render, although path will never be nil
+  # @param [String] path path to destination file
+  def self.render(path = nil)
+    if path.nil?
+      puts generate
+      exit
+    else
+      File.open(path, 'w') { |file| file.write(generate) }
+      YARD::Logger.instance.debug "Wrote markdown to #{path}"
+    end
+  end
+end

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

@@ -0,0 +1,168 @@
+require 'puppet-strings'
+require 'puppet-strings/json'
+require 'puppet-strings/yard'
+
+module PuppetStrings::Markdown
+  # This class makes elements in a YARD::Registry hash easily accessible for templates.
+  #
+  # Here's an example hash:
+  #{:name=>:klass,
+  # :file=>"(stdin)",
+  # :line=>16,
+  # :inherits=>"foo::bar",
+  # :docstring=>
+  #  {:text=>"An overview for a simple class.",
+  #   :tags=>
+  #    [{:tag_name=>"summary", :text=>"A simple class."},
+  #     {:tag_name=>"since", :text=>"1.0.0"},
+  #     {:tag_name=>"see", :name=>"www.puppet.com"},
+  #     {:tag_name=>"example",
+  #      :text=>
+  #       "class { 'klass':\n" +
+  #       "  param1 => 1,\n" +
+  #       "  param3 => 'foo',\n" +
+  #       "}",
+  #      :name=>"This is an example"},
+  #     {:tag_name=>"author", :text=>"eputnam"},
+  #     {:tag_name=>"option", :name=>"opts"},
+  #     {:tag_name=>"raise", :text=>"SomeError"},
+  #     {: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=>{"param1"=>"1", "param2"=>"undef", "param3"=>"'hi'"},
+  # :source=>
+  #  "class klass (\n" +
+  #  "  Integer $param1 = 1,\n" +
+  #  "  $param2 = undef,\n" +
+  #  "  String $param3 = 'hi'\n" +
+  #  ") inherits foo::bar {\n" +
+  #  "}"}
+  class Base
+    def initialize(registry, component_type)
+      @type = component_type
+      @registry = registry
+      @tags = registry[:docstring][:tags] || []
+    end
+
+    # generate 1:1 tag methods
+    # e.g. {:tag_name=>"author", :text=>"eputnam"}
+    { :return_val => 'return',
+      :since => 'since',
+      :summary => 'summary' }.each do |method_name, tag_name|
+      # @return [String] unless the tag is nil or the string.length == 0
+      define_method method_name do
+        @tags.select { |tag| tag[:tag_name] == "#{tag_name}" }[0][:text] unless @tags.select { |tag| tag[:tag_name] == "#{tag_name}" }[0].nil? || @tags.select { |tag| tag[:tag_name] == "#{tag_name}" }[0][:text].length.zero?
+      end
+    end
+
+    # @return [String] top-level name
+    def name
+      @registry[:name].to_s unless @registry[:name].nil?
+    end
+
+    # @return [String] 'Overview' text (untagged text)
+    def text
+      @registry[:docstring][:text] unless @registry[:docstring][:text].empty?
+    end
+
+    # @return [String] data type of return value
+    def return_type
+      @tags.select { |tag| tag[:tag_name] == 'return' }[0][:types][0] unless @tags.select { |tag| tag[:tag_name] == 'return' }[0].nil?
+    end
+
+    # @return [String] text from @since tag
+    def since
+      @tags.select { |tag| tag[:tag_name] == 'since' }[0][:text] unless @tags.select { |tag| tag[:tag_name] == 'since' }[0].nil?
+    end
+
+    # @return [Array] @see tag hashes
+    def see
+      @tags.select { |tag| tag[:tag_name] == 'see' } unless @tags.select { |tag| tag[:tag_name] == 'see' }[0].nil?
+    end
+
+    # @return [Array] parameter tag hashes
+    def params
+      @tags.select { |tag| tag[:tag_name] == 'param' } unless @tags.select { |tag| tag[:tag_name] == 'param' }[0].nil?
+    end
+
+    # @return [Array] example tag hashes
+    def examples
+      @tags.select { |tag| tag[:tag_name] == 'example' } unless @tags.select { |tag| tag[:tag_name] == 'example' }[0].nil?
+    end
+
+    # @return [Array] raise tag hashes
+    def raises
+      @tags.select { |tag| tag[:tag_name] == 'raise' } unless @tags.select { |tag| tag[:tag_name] == 'raise' }[0].nil?
+    end
+
+    # @return [Array] option tag hashes
+    def options
+      @tags.select { |tag| tag[:tag_name] == 'option' } unless @tags.select { |tag| tag[:tag_name] == 'option' }[0].nil?
+    end
+
+    # @param parameter_name
+    #   parameter name to match to option tags
+    # @return [Array] option tag hashes that have a parent parameter_name
+    def options_for_param(parameter_name)
+      opts_for_p = options.select { |o| o[:parent] == parameter_name } unless options.nil?
+      opts_for_p unless opts_for_p.nil? || opts_for_p.length.zero?
+    end
+
+    # @return [Array] any defaults found for the component
+    def defaults
+      @registry[:defaults] unless @registry[:defaults].nil?
+    end
+
+    # @return [Hash] information needed for the table of contents
+    def toc_info
+      {
+        name: name.to_s,
+        link: link,
+        desc: summary || @registry[:docstring][:text][0..140].gsub("\n",' '),
+        private: private?
+      }
+    end
+
+    # @return [String] makes the component name suitable for a GitHub markdown link
+    def link
+      name.delete('::').strip.gsub(' ','-').downcase
+    end
+
+    # Some return, default, or valid values need to be in backticks. Instead of fu in the handler or code_object, this just does the change on the front.
+    # @param value
+    #  any string
+    # @return [String] value or value in backticks if it is in a list
+    def value_string(value)
+      to_symbol = %w[undef true false]
+      if to_symbol.include? value
+        return "`#{value}`"
+      else
+        return value
+      end
+    end
+
+    def private?
+      result = false
+      api = @tags.find { |tag| tag[:tag_name] == 'api' }
+      unless api.nil?
+        result = api[:text] == 'private' ? true : false
+      end
+      result
+    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)
+    end
+  end
+end