From 784c32c979a101c2e722a0d934aead133b8bdcfa Mon Sep 17 00:00:00 2001 From: Eric Putnam Date: Mon, 26 Feb 2018 15:36:28 -0800 Subject: [PATCH 1/4] (maint) update rake tasks --- lib/puppet-strings/tasks/generate.rb | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/lib/puppet-strings/tasks/generate.rb b/lib/puppet-strings/tasks/generate.rb index 91a931c..47c7a39 100644 --- a/lib/puppet-strings/tasks/generate.rb +++ b/lib/puppet-strings/tasks/generate.rb @@ -3,7 +3,7 @@ require 'puppet-strings' # Implements the strings:generate task. namespace :strings do desc 'Generate Puppet documentation with YARD.' - task :generate, :patterns, :debug, :backtrace, :markup, :json, :yard_args do |t, args| + task :generate, :patterns, :debug, :backtrace, :markup, :json, :markdown, :yard_args do |t, args| patterns = args[:patterns] patterns = patterns.split if patterns patterns ||= PuppetStrings::DEFAULT_SEARCH_PATTERNS @@ -17,6 +17,7 @@ namespace :strings do # rubocop:disable Style/PreferredHashMethods # `args` is a Rake::TaskArguments and has no key? method options[:json] = args[:json] if args.has_key? :json + options[:markdown] = args[:markdown] if args.has_key? :markdown options[:yard_args] = args[:yard_args].split if args.has_key? :yard_args # rubocop:enable Style/PreferredHashMethods From 6ffefc472b218cd7131dacb5fb8f8463274714b2 Mon Sep 17 00:00:00 2001 From: Eric Putnam Date: Mon, 26 Feb 2018 16:23:20 -0800 Subject: [PATCH 2/4] release prep and gcg config --- CHANGELOG.md | 21 +++++++++++++++++++++ Gemfile | 1 + README.md | 1 + Rakefile | 27 +++++++++++++++++++++++++++ puppet-strings.gemspec | 2 +- 5 files changed, 51 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4f6e323..caf141a 100644 --- a/CHANGELOG.md +++ b/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)* \ No newline at end of file diff --git a/Gemfile b/Gemfile index 767d341..c762fe5 100644 --- a/Gemfile +++ b/Gemfile @@ -5,6 +5,7 @@ gemspec gem 'rgen' gem 'redcarpet' gem 'yard', '~> 0.9.11' +gem 'github_changelog_generator', git: 'https://github.com/skywinder/github-changelog-generator', ref: 'master' if ENV['PUPPET_GEM_VERSION'] gem 'puppet', ENV['PUPPET_GEM_VERSION'], :require => false diff --git a/README.md b/README.md index 958f806..2515d22 100644 --- a/README.md +++ b/README.md @@ -463,6 +463,7 @@ function example(string $name) { ### Available Strings tags +* `@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. diff --git a/Rakefile b/Rakefile index b4adc98..fddca7e 100644 --- a/Rakefile +++ b/Rakefile @@ -1,6 +1,7 @@ require 'rubygems' require 'puppetlabs_spec_helper/rake_tasks' require 'puppet-lint/tasks/puppet-lint' +require 'github_changelog_generator/task' # Add our own tasks require 'puppet-strings/tasks' @@ -8,6 +9,32 @@ require 'puppet-strings/tasks' PuppetLint.configuration.send('disable_80chars') PuppetLint.configuration.ignore_paths = %w(acceptance/**/*.pp spec/**/*.pp pkg/**/*.pp) +GitHubChangelogGenerator::RakeTask.new :changelog do |config| + config.user = 'puppetlabs' + config.project = 'puppet-strings' + config.since_tag = '1.1.1' + config.future_release = '1.2.0' + config.exclude_labels = ['maintenance'] + config.header = "# Change log\n\nAll 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)." + config.add_pr_wo_labels = true + config.issues = false + config.merge_prefix = "### UNCATEGORIZED PRS; GO LABEL THEM" + config.configure_sections = { + "Changed" => { + "prefix" => "### Changed", + "labels" => ["backwards-incompatible"], + }, + "Added" => { + "prefix" => "### Added", + "labels" => ["feature", "enhancement"], + }, + "Fixed" => { + "prefix" => "### Fixed", + "labels" => ["bugfix"], + }, + } +end + desc 'Validate Ruby source files and ERB templates.' task :validate do Dir['spec/**/*.rb','lib/**/*.rb'].each do |ruby_file| diff --git a/puppet-strings.gemspec b/puppet-strings.gemspec index eb8be88..960b806 100644 --- a/puppet-strings.gemspec +++ b/puppet-strings.gemspec @@ -1,7 +1,7 @@ Gem::Specification.new do |s| s.name = 'puppet-strings' s.author = 'Puppet Inc.' - s.version = '1.1.1' + s.version = '1.2.0' s.license = 'Apache-2.0' s.summary = 'Puppet documentation via YARD' s.email = 'info@puppet.com' From 567ee8aac940928991b7120107f8324649cc681f Mon Sep 17 00:00:00 2001 From: Eric Putnam Date: Tue, 27 Feb 2018 10:31:00 -0800 Subject: [PATCH 3/4] hold off on gcg The version of github changelog generator we want to use requires a version of Ruby we can't yet guarantee. This reverts all the plumbing for gcg while still committing the changelog --- Gemfile | 1 - Rakefile | 27 --------------------------- 2 files changed, 28 deletions(-) diff --git a/Gemfile b/Gemfile index c762fe5..767d341 100644 --- a/Gemfile +++ b/Gemfile @@ -5,7 +5,6 @@ gemspec gem 'rgen' gem 'redcarpet' gem 'yard', '~> 0.9.11' -gem 'github_changelog_generator', git: 'https://github.com/skywinder/github-changelog-generator', ref: 'master' if ENV['PUPPET_GEM_VERSION'] gem 'puppet', ENV['PUPPET_GEM_VERSION'], :require => false diff --git a/Rakefile b/Rakefile index fddca7e..b4adc98 100644 --- a/Rakefile +++ b/Rakefile @@ -1,7 +1,6 @@ require 'rubygems' require 'puppetlabs_spec_helper/rake_tasks' require 'puppet-lint/tasks/puppet-lint' -require 'github_changelog_generator/task' # Add our own tasks require 'puppet-strings/tasks' @@ -9,32 +8,6 @@ require 'puppet-strings/tasks' PuppetLint.configuration.send('disable_80chars') PuppetLint.configuration.ignore_paths = %w(acceptance/**/*.pp spec/**/*.pp pkg/**/*.pp) -GitHubChangelogGenerator::RakeTask.new :changelog do |config| - config.user = 'puppetlabs' - config.project = 'puppet-strings' - config.since_tag = '1.1.1' - config.future_release = '1.2.0' - config.exclude_labels = ['maintenance'] - config.header = "# Change log\n\nAll 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)." - config.add_pr_wo_labels = true - config.issues = false - config.merge_prefix = "### UNCATEGORIZED PRS; GO LABEL THEM" - config.configure_sections = { - "Changed" => { - "prefix" => "### Changed", - "labels" => ["backwards-incompatible"], - }, - "Added" => { - "prefix" => "### Added", - "labels" => ["feature", "enhancement"], - }, - "Fixed" => { - "prefix" => "### Fixed", - "labels" => ["bugfix"], - }, - } -end - desc 'Validate Ruby source files and ERB templates.' task :validate do Dir['spec/**/*.rb','lib/**/*.rb'].each do |ruby_file| From dde16375d04e8d6bd8bb491085380ce002a4e0ce Mon Sep 17 00:00:00 2001 From: Eric Putnam Date: Tue, 27 Feb 2018 16:02:30 -0800 Subject: [PATCH 4/4] (maint) actually update rake task --- lib/puppet-strings/tasks/generate.rb | 30 ++++++++++++++++++++++------ 1 file changed, 24 insertions(+), 6 deletions(-) diff --git a/lib/puppet-strings/tasks/generate.rb b/lib/puppet-strings/tasks/generate.rb index 47c7a39..8046544 100644 --- a/lib/puppet-strings/tasks/generate.rb +++ b/lib/puppet-strings/tasks/generate.rb @@ -3,7 +3,7 @@ require 'puppet-strings' # Implements the strings:generate task. namespace :strings do desc 'Generate Puppet documentation with YARD.' - task :generate, :patterns, :debug, :backtrace, :markup, :json, :markdown, :yard_args do |t, args| + task :generate, [:patterns, :debug, :backtrace, :markup, :json, :markdown, :yard_args] do |t, args| patterns = args[:patterns] patterns = patterns.split if patterns patterns ||= PuppetStrings::DEFAULT_SEARCH_PATTERNS @@ -14,12 +14,30 @@ namespace :strings do markup: args[:markup] || 'markdown', } - # rubocop:disable Style/PreferredHashMethods - # `args` is a Rake::TaskArguments and has no key? method - options[:json] = args[:json] if args.has_key? :json - options[:markdown] = args[:markdown] if args.has_key? :markdown + raise("Error: Both JSON and Markdown output have been selected. Please select one.") if args[:json] == 'true' && args[:markdown] == 'true' + + # rubocop:disable Style/PreferredHashMethods + # Because of Ruby, true and false from the args are both strings and both true. Here, + # when the arg is set to false (or empty), set it to real false, else real true. Then, + # if the arg is set simply to 'true', assume default behavior is expected and set the path + # to nil to elicit that, else set to the path given. + # @param [Hash] args from the Rake task cli + # @param [Hash] options to send to the generate function + # @param [Symbol] possible format option + # @return nil + def parse_format_option(args, options, format) + if args.has_key? format + options[format] = args[format] == 'false' || args[format].empty? ? false : true + if options[format] + options[:path] = args[format] == 'true' ? nil : args[format] + end + end + end + + [:json,:markdown].each { |format| parse_format_option(args, options, format) } + + warn('yard_args behavior is a little dodgy, use at your own risk') if args[:yard_args] options[:yard_args] = args[:yard_args].split if args.has_key? :yard_args - # rubocop:enable Style/PreferredHashMethods PuppetStrings.generate(patterns, options) end