diff --git a/Gemfile b/Gemfile index 63148a3..c98da00 100644 --- a/Gemfile +++ b/Gemfile @@ -1,9 +1,9 @@ source 'https://rubygems.org' -gem 'yard' +gemspec + gem 'rgen' gem 'redcarpet' -gem 'puppet-strings', '0.1.0', :path => '.' puppetversion = ENV['PUPPET_VERSION'] diff --git a/README.md b/README.md index 6114711..c7e3fb3 100644 --- a/README.md +++ b/README.md @@ -77,8 +77,8 @@ Running Puppet Strings Once strings has been installed you can document a puppet module: ``` - $ cd /path/to/module - $ puppet strings +$ cd /path/to/module +$ puppet strings ``` This processes `README` and all puppet and ruby files under `manifests/` @@ -87,7 +87,7 @@ and `lib/`. To document specific files: ``` - $ puppet strings some_manifest.pp [another_if_you_feel_like_it.rb] +$ puppet strings some_manifest.pp [another_if_you_feel_like_it.rb] ``` Processing is delegated to the `yardoc` tool so some options listed in `yard @@ -99,7 +99,7 @@ In addition to generating a directory full of HTML, you can also serve up documentation for all your modules using the `server` action: ``` - $ puppet strings server +$ puppet strings server ``` Writing Compatible Documentation @@ -113,7 +113,7 @@ would like YARD to use by adding a `.yardopts` file to the root of your module directory which specifies the desired format: ``` - --markup markdown +--markup markdown ``` While we have yet to decide exactly how documentation should work in the @@ -124,43 +124,43 @@ style guide. ### Functions Here's an example of how you might document a 4x function: -``` - # When given two numbers, returns the one that is larger. - # You could have a several line description here if you wanted, - # but I don't have much to say about this function. - # - # @example using two integers - # $bigger_int = max(int_one, int_two) - # - # @return [Integer] the larger of the two parameters - # - # @param num_a [Integer] the first number to be compared - # @param num_b [Integer] the second number to be compared - Puppet::Functions.create_function(:max) do - def max(num_a, num_b) - num_a >= num_b ? num_a : num_b - end - end +```ruby +# When given two numbers, returns the one that is larger. +# You could have a several line description here if you wanted, +# but I don't have much to say about this function. +# +# @example using two integers +# $bigger_int = max(int_one, int_two) +# +# @return [Integer] the larger of the two parameters +# +# @param num_a [Integer] the first number to be compared +# @param num_b [Integer] the second number to be compared +Puppet::Functions.create_function(:max) do + def max(num_a, num_b) + num_a >= num_b ? num_a : num_b + end +end ``` ### Classes / Defined Types Here's an example of how you might document a class: -``` - # This class is meant to serve as an example of how one might - # want to document a manifest in a way that is compatible. - # with the strings module - # - # @example when declaring the example class - # include example - # - # @param first_arg The first parameter for this class - # @param second_arg The second paramter for this class - class example ( - $first_arg = $example::params::first_arg, - $second_arg = $exampe::params::second_arg, - ) { } +```puppet +# This class is meant to serve as an example of how one might +# want to document a manifest in a way that is compatible. +# with the strings module +# +# @example when declaring the example class +# include example +# +# @param first_arg The first parameter for this class +# @param second_arg The second paramter for this class +class example ( + $first_arg = $example::params::first_arg, + $second_arg = $exampe::params::second_arg, +) { } ``` ### Types and Providers @@ -204,6 +204,20 @@ 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`: + +```ruby +gem 'puppet-strings', :git => 'https://github.com/puppetlabs/puppet-strings.git' +``` + +To use the rake tasks, `require puppet-strings/rake_tasks` in your `Rakefile`: + +```ruby +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..328a9b4 --- /dev/null +++ b/lib/puppet_x/puppetlabs/strings/util.rb @@ -0,0 +1,59 @@ +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 + YARD::Tags::Library.define_directive("puppet.type.param", + :with_types_and_name, + PuppetX::PuppetLabs::Strings::YARD::Tags::PuppetTypeParameterDirective) + + 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..1aef237 --- /dev/null +++ b/puppet-strings.gemspec @@ -0,0 +1,19 @@ +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' + + %w(author version license summary).each do |section| + s.send("#{section}=", puppet_metadata[section]) + end + + s.email = 'info@puppetlabs.com' + 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', '~> 0.8' +end