diff --git a/Gemfile b/Gemfile index 63148a3..2bf86c4 100644 --- a/Gemfile +++ b/Gemfile @@ -1,9 +1,10 @@ source 'https://rubygems.org' +gemspec + gem 'yard' gem 'rgen' gem 'redcarpet' -gem 'puppet-strings', '0.1.0', :path => '.' puppetversion = ENV['PUPPET_VERSION'] diff --git a/README.md b/README.md index 6cce365..7de39a6 100644 --- a/README.md +++ b/README.md @@ -204,6 +204,16 @@ Here are a few other good resources for getting started with documentation: * [YARD Getting Started Guide](http://www.rubydoc.info/gems/yard/file/docs/GettingStarted.md) * [YARD Tags Overview](http://www.rubydoc.info/gems/yard/file/docs/Tags.md) +Rake Tasks +----- + +This module is also available as a Gem and makes two rake tasks (`generate` and `serve`) available in `puppet-strings/rake_tasks`. To add this to your module's CI workflow, be sure to add this module to your `Gemfile`: + + gem 'puppet-strings', :git => 'https://github.com/puppetlabs/puppet-strings.git' + +To use the rake tasks, `require puppet-strings/rake_tasks` in your `Rakefile`: + + require 'puppet-strings/rake_tasks' Developing and Contributing ----- diff --git a/lib/puppet-strings/rake_tasks.rb b/lib/puppet-strings/rake_tasks.rb new file mode 100644 index 0000000..3b3cb33 --- /dev/null +++ b/lib/puppet-strings/rake_tasks.rb @@ -0,0 +1,16 @@ +require 'rake' +require 'rake/tasklib' +require 'puppet/face' +require 'puppet_x/puppetlabs/strings/util' + +namespace :strings do + desc 'Generate Puppet documentation with YARD.' + task :generate do + PuppetX::PuppetLabs::Strings::Util.generate + end + + desc 'Serve YARD documentation for modules.' + task :serve do + PuppetX::PuppetLabs::Strings::Util.serve + end +end diff --git a/lib/puppet/face/strings.rb b/lib/puppet/face/strings.rb index 3ae536d..9cea6cb 100644 --- a/lib/puppet/face/strings.rb +++ b/lib/puppet/face/strings.rb @@ -19,13 +19,6 @@ Puppet::Face.define(:strings, '0.0.1') do end end - # A list of globs that generates the default list of module files from which - # documentation can be extracted. - # - # TODO: It would be awesome if we could somehow override/append to the - # default file list that YARD uses. Consider an upstream PR for this. - MODULE_SOURCEFILES = ['manifests/**/*.pp', 'lib/**/*.rb'] - action(:yardoc) do default @@ -34,33 +27,9 @@ Puppet::Face.define(:strings, '0.0.1') do when_invoked do |*args| check_required_features - require 'puppet_x/puppetlabs/strings/actions' + require 'puppet_x/puppetlabs/strings/util' - yardoc_actions = PuppetX::PuppetLabs::Strings::Actions.new(Puppet[:debug], Puppet[:trace]) - - # The last element of the argument array should be the options hash. - # We don't have any options yet, so for now just pop the hash off and - # toss it. - # - # NOTE: The Puppet Face will throw 'unrecognized option' errors if any - # YARD options are passed to it. The best way to approach this problem is - # by using the `.yardopts` file. YARD will autoload any options placed in - # that file. - args.pop - - # For now, assume the remaining positional args are a list of manifest - # and ruby files to parse. - yard_args = (args.empty? ? MODULE_SOURCEFILES : args) - - # This line monkeypatches yard's progress indicator so it doesn't write - # all over the terminal. This should definitely not be in real code, but - # it's very handy for debugging with pry - #class YARD::Logger; def progress(*args); end; end - YARD::Tags::Library.define_directive("puppet.type.param", - :with_types_and_name, - PuppetX::PuppetLabs::Strings::YARD::Tags::PuppetTypeParameterDirective) - - yardoc_actions.generate_documentation(*yard_args) + PuppetX::PuppetLabs::Strings::Util.generate(args) # Puppet prints the return value of the action. The return value of this # action is that of the yardoc_actions invocation, which is the boolean @@ -80,32 +49,9 @@ Puppet::Face.define(:strings, '0.0.1') do when_invoked do |*args| check_required_features - require 'puppet_x/puppetlabs/strings/actions' + require 'puppet_x/puppetlabs/strings/util' - server_actions = PuppetX::PuppetLabs::Strings::Actions.new(Puppet[:debug], Puppet[:trace]) - - args.pop - - module_names = args - - # FIXME: This is pretty inefficient as it forcibly re-generates the YARD - # indicies each time the server is started. However, it ensures things are - # generated properly. - module_list = server_actions.index_documentation_for_modules(module_names, MODULE_SOURCEFILES) - - module_tuples = server_actions.generate_module_tuples(module_list) - - module_tuples.map! do |mod| - [mod[:name], mod[:index_path]] - end - - # The `-m` flag means a list of name/path pairs will follow. The name is - # used as the module name and the path indicates which `.yardoc` index to - # generate documentation from. - yard_args = %w[-m -q] + module_tuples.flatten - - server_actions.serve_documentation(*yard_args) + PuppetX::PuppetLabs::Strings::Util.serve(args) end end end - diff --git a/lib/puppet_x/puppetlabs/strings/util.rb b/lib/puppet_x/puppetlabs/strings/util.rb new file mode 100644 index 0000000..989c2ff --- /dev/null +++ b/lib/puppet_x/puppetlabs/strings/util.rb @@ -0,0 +1,56 @@ +require 'puppet_x/puppetlabs/strings/actions' + +module PuppetX::PuppetLabs::Strings::Util + MODULE_SOURCEFILES = ['manifests/**/*.pp', 'lib/**/*.rb'] + + def self.generate(args = []) + yardoc_actions = PuppetX::PuppetLabs::Strings::Actions.new(Puppet[:debug], Puppet[:trace]) + + # The last element of the argument array should be the options hash. + # We don't have any options yet, so for now just pop the hash off and + # toss it. + # + # NOTE: The Puppet Face will throw 'unrecognized option' errors if any + # YARD options are passed to it. The best way to approach this problem is + # by using the `.yardopts` file. YARD will autoload any options placed in + # that file. + args.pop + + # For now, assume the remaining positional args are a list of manifest + # and ruby files to parse. + yard_args = (args.empty? ? MODULE_SOURCEFILES : args) + + # This line monkeypatches yard's progress indicator so it doesn't write + # all over the terminal. This should definitely not be in real code, but + # it's very handy for debugging with pry + #class YARD::Logger; def progress(*args); end; end + + yardoc_actions.generate_documentation(*yard_args) + end + + def self.serve(args = []) + server_actions = PuppetX::PuppetLabs::Strings::Actions.new(Puppet[:debug], Puppet[:trace]) + + args.pop + + module_names = args + + # FIXME: This is pretty inefficient as it forcibly re-generates the YARD + # indicies each time the server is started. However, it ensures things are + # generated properly. + module_list = server_actions.index_documentation_for_modules(module_names, MODULE_SOURCEFILES) + + module_tuples = server_actions.generate_module_tuples(module_list) + + module_tuples.map! do |mod| + [mod[:name], mod[:index_path]] + end + + # The `-m` flag means a list of name/path pairs will follow. The name is + # used as the module name and the path indicates which `.yardoc` index to + # generate documentation from. + yard_args = %w[-m -q] + module_tuples.flatten + + server_actions.serve_documentation(*yard_args) + end +end diff --git a/puppet-strings.gemspec b/puppet-strings.gemspec new file mode 100644 index 0000000..6f88e84 --- /dev/null +++ b/puppet-strings.gemspec @@ -0,0 +1,18 @@ +require 'json' + +puppet_metadata = JSON.load File.open(File.expand_path(File.join(__FILE__, '..', 'metadata.json'))).read + +Gem::Specification.new do |s| + s.name = 'puppet-strings' + s.author = puppet_metadata['author'] + s.version = puppet_metadata['version'] + s.license = puppet_metadata['license'] + s.summary = puppet_metadata['summary'] + s.homepage = puppet_metadata['project_page'] + + s.description = s.summary + s.files = Dir['lib/**/*'].reject { |f| f if File.directory?(f) } + + s.add_runtime_dependency 'puppet', '>= 3.7.0' + s.add_runtime_dependency 'yard' +end