kienan
/
puppet-strings
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Merge pull request #54 from danzilio/gem 

(PDOC-28) Make puppet strings available as a gem
This commit is contained in:
Hailee Kenney 2015-10-07 11:00:43 -07:00
parent 5206c8c62e 4845bc2a0d
commit d033183002
6 changed files with 150 additions and 96 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
Gemfile
View File

@ -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']

86
README.md
View File

@ -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
-----

16
lib/puppet-strings/rake_tasks.rb Normal file
View File

@ -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

62
lib/puppet/face/strings.rb
View File

@ -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

59
lib/puppet_x/puppetlabs/strings/util.rb Normal file
View File

@ -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

19
puppet-strings.gemspec Normal file
View File

@ -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