Merge pull request #50 from tremble/master

RDoc cleanup

README

@@ -0,0 +1,94 @@
+== Module: concat
+
+A system to construct files using fragments from other files or templates.
+
+This requires at least puppet 0.25 to work correctly as we use some
+enhancements in recursive directory management and regular expressions
+to do the work here.
+
+=== Usage:
+
+The basic use case is as below:
+
+ concat{"/etc/named.conf":
+   notify => Service["named"]
+ }
+
+ concat::fragment{"foo.com_config":
+   target  => "/etc/named.conf",
+   order   => 10,
+   content => template("named_conf_zone.erb")
+ }
+
+ # add a fragment not managed by puppet so local users
+ # can add content to managed file
+ concat::fragment{"foo.com_user_config":
+   target  => "/etc/named.conf",
+   order   => 12,
+   ensure  => "/etc/named.conf.local"
+ }
+
+This will use the template named_conf_zone.erb to build a single
+bit of config up and put it into the fragments dir.  The file
+will have an number prefix of 10, you can use the order option
+to control that and thus control the order the final file gets built in.
+
+You can also specify a path and use a different name for your resources:
+
+ # You can make this something dynamic, based on whatever parameters your
+ # module/class for example.
+ $vhost_file = '/etc/httpd/vhosts/01-my-vhost.conf'
+
+ concat{'apache-vhost-myvhost':
+  path => $vhost_file,
+ }
+
+ # We don't care where the file is located, just what to put in it.
+ concat::fragment {'apache-vhost-myvhost-main':
+  target  => 'apache-vhost-myvhost',
+  content => '<virtualhost *:80>',
+  order   => 01,
+ }
+
+ concat::fragment {'apache-vhost-myvhost-close':
+  target  => 'apache-vhost-myvhost',
+  content => '</virtualhost>',
+  order   => 99,
+ }
+
+=== Setup:
+
+The class concat::setup uses the fact concat_basedir to define the variable
+$concatdir, where all the temporary files and fragments will be
+durably stored. The fact concat_basedir will be set up on the client to
+<Puppet[:vardir]>/concat, so you will be able to run different setup/flavours
+of puppet clients.
+However, since this requires the file lib/facter/concat_basedir.rb to be
+deployed on the clients, so you will have to set "pluginsync = true" on
+both the master and client, at least for the first run.
+
+There's some regular expression magic to figure out the puppet version but
+if you're on an older 0.24 version just set $puppetversion = 24
+
+=== Detail:
+
+We use a helper shell script called concatfragments.sh that gets placed
+in <Puppet[:vardir]>/concat/bin to do the concatenation.  While this might
+seem more complex than some of the one-liner alternatives you might find on
+the net we do a lot of error checking and safety checks in the script to avoid
+problems that might be caused by complex escaping errors etc.
+
+=== License:
+
+Apache Version 2
+
+=== Latest:
+
+http://github.com/ripienaar/puppet-concat/
+
+=== Contact:
+
+* R.I.Pienaar <rip@devco.net>
+* Volcane on freenode
+* @ripienaar on twitter
+* www.devco.net

lib/facter/concat_basedir.rb

@@ -1,3 +1,9 @@
+# == Fact: concat_basedir
+#
+# A custom fact that sets the default location for fragments
+#
+# "${::vardir}/concat/"
+#
 Facter.add("concat_basedir") do
     setcode do
         File.join(Puppet[:vardir],"concat")

manifests/fragment.pp

@@ -1,19 +1,40 @@
+# == Define: concat::fragment
+#
 # Puts a file fragment into a directory previous setup using concat
 #
-# OPTIONS:
+# === Options:
-#   - target    The file that these fragments belong to
+#
-#   - content   If present puts the content into the file
+# [*target*]
-#   - source    If content was not specified, use the source
+#   The file that these fragments belong to
-#   - order     By default all files gets a 10_ prefix in the directory
+# [*content*]
-#               you can set it to anything else using this to influence the
+#   If present puts the content into the file
-#               order of the content in the file
+# [*source*]
-#   - ensure    Present/Absent or destination to a file to include another file
+#   If content was not specified, use the source
-#   - mode      Mode for the file
+# [*order*]
-#   - owner     Owner of the file
+#   By default all files gets a 10_ prefix in the directory you can set it to
-#   - group     Owner of the file
+#   anything else using this to influence the order of the content in the file
-#   - backup    Controls the filebucketing behavior of the final file and
+# [*ensure*]
-#               see File type reference for its use.  Defaults to 'puppet'
+#   Present/Absent or destination to a file to include another file
-define concat::fragment($target, $content=undef, $source=undef, $order=10, $ensure = 'present', $mode = '0644', $owner = $::id, $group = $concat::setup::root_group, $backup = 'puppet') {
+# [*mode*]
+#   Mode for the file
+# [*owner*]
+#   Owner of the file
+# [*group*]
+#   Owner of the file
+# [*backup*]
+#   Controls the filebucketing behavior of the final file and see File type
+#   reference for its use.  Defaults to 'puppet'
+#
+define concat::fragment(
+    $target,
+    $content=undef,
+    $source=undef,
+    $order=10,
+    $ensure = 'present',
+    $mode = '0644',
+    $owner = $::id,
+    $group = $concat::setup::root_group,
+    $backup = 'puppet') {
   $safe_name = regsubst($name, '[/\n]', '_', 'GM')
   $safe_target_name = regsubst($target, '[/\n]', '_', 'GM')
   $concatdir = $concat::setup::concatdir

manifests/init.pp

@@ -1,128 +1,50 @@
-# A system to construct files using fragments from other files or templates.
+# == Define: concat
 #
-# This requires at least puppet 0.25 to work correctly as we use some
-# enhancements in recursive directory management and regular expressions
-# to do the work here.
-#
-# USAGE:
-# The basic use case is as below:
-#
-# concat{"/etc/named.conf":
-#    notify => Service["named"]
-# }
-#
-# concat::fragment{"foo.com_config":
-#    target  => "/etc/named.conf",
-#    order   => 10,
-#    content => template("named_conf_zone.erb")
-# }
-#
-# # add a fragment not managed by puppet so local users
-# # can add content to managed file
-# concat::fragment{"foo.com_user_config":
-#    target  => "/etc/named.conf",
-#    order   => 12,
-#    ensure  => "/etc/named.conf.local"
-# }
-#
-# This will use the template named_conf_zone.erb to build a single
-# bit of config up and put it into the fragments dir.  The file
-# will have an number prefix of 10, you can use the order option
-# to control that and thus control the order the final file gets built in.
-#
-# You can also specify a path and use a different name for your resources:
-#
-# # You can make this something dynamic, based on whatever parameters your
-# # module/class for example.
-# $vhost_file = '/etc/httpd/vhosts/01-my-vhost.conf'
-#
-# concat{'apache-vhost-myvhost':
-#   path => $vhost_file,
-# }
-#
-# # We don't care where the file is located, just what to put in it.
-# concat::fragment {'apache-vhost-myvhost-main':
-#   target  => 'apache-vhost-myvhost',
-#   content => '<virtualhost *:80>',
-#   order   => 01,
-# }
-#
-# concat::fragment {'apache-vhost-myvhost-close':
-#   target  => 'apache-vhost-myvhost',
-#   content => '</virtualhost>',
-#   order   => 99,
-# }
-#
-#
-# SETUP:
-# The class concat::setup uses the fact concat_basedir to define the variable
-# $concatdir, where all the temporary files and fragments will be
-# durably stored. The fact concat_basedir will be set up on the client to
-# <Puppet[:vardir]>/concat, so you will be able to run different setup/flavours
-# of puppet clients.
-# However, since this requires the file lib/facter/concat_basedir.rb to be
-# deployed on the clients, so you will have to set "pluginsync = true" on
-# both the master and client, at least for the first run.
-#
-# There's some regular expression magic to figure out the puppet version but
-# if you're on an older 0.24 version just set $puppetversion = 24
-#
-# DETAIL:
-# We use a helper shell script called concatfragments.sh that gets placed
-# in <Puppet[:vardir]>/concat/bin to do the concatenation.  While this might
-# seem more complex than some of the one-liner alternatives you might find on
-# the net we do a lot of error checking and safety checks in the script to avoid
-# problems that might be caused by complex escaping errors etc.
-#
-# LICENSE:
-# Apache Version 2
-#
-# LATEST:
-# http://github.com/ripienaar/puppet-concat/
-#
-# CONTACT:
-# R.I.Pienaar <rip@devco.net>
-# Volcane on freenode
-# @ripienaar on twitter
-# www.devco.net
-
-
 # Sets up so that you can use fragments to build a final config file,
 #
-# OPTIONS:
+# === Options:
-#  - path       The path to the final file. Use this in case you want to
-#               differentiate between the name of a resource and the file path.
-#               Note: Use the name you provided in the target of your
-#               fragments.
-#  - mode       The mode of the final file
-#  - owner      Who will own the file
-#  - group      Who will own the file
-#  - force      Enables creating empty files if no fragments are present
-#  - warn       Adds a normal shell style comment top of the file indicating
-#               that it is built by puppet
-#  - backup     Controls the filebucketing behavior of the final file and
-#               see File type reference for its use.  Defaults to 'puppet'
-#  - replace    Whether to replace a file that already exists on the local
-#               system
 #
-# ACTIONS:
+# [*path*]
-#  - Creates fragment directories if it didn't exist already
+#   The path to the final file. Use this in case you want to differentiate
-#  - Executes the concatfragments.sh script to build the final file, this
+#   between the name of a resource and the file path.  Note: Use the name you
-#    script will create directory/fragments.concat.   Execution happens only
+#   provided in the target of your fragments.
-#    when:
+# [*mode*]
-#    * The directory changes
+#   The mode of the final file
-#    * fragments.concat != final destination, this means rebuilds will happen
+# [*owner*]
-#      whenever someone changes or deletes the final file.  Checking is done
+#   Who will own the file
-#      using /usr/bin/cmp.
+# [*group*]
-#    * The Exec gets notified by something else - like the concat::fragment
+#   Who will own the file
-#      define
+# [*force*]
-#  - Copies the file over to the final destination using a file resource
+#   Enables creating empty files if no fragments are present
+# [*warn*]
+#   Adds a normal shell style comment top of the file indicating that it is
+#   built by puppet
+# [*backup*]
+#   Controls the filebucketing behavior of the final file and see File type
+#   reference for its use.  Defaults to 'puppet'
+# [*replace*]
+#   Whether to replace a file that already exists on the local system
+#
+# === Actions:
+# * Creates fragment directories if it didn't exist already
+# * Executes the concatfragments.sh script to build the final file, this
+#   script will create directory/fragments.concat.   Execution happens only
+#   when:
+#   * The directory changes
+#   * fragments.concat != final destination, this means rebuilds will happen
+#     whenever someone changes or deletes the final file.  Checking is done
+#     using /usr/bin/cmp.
+#   * The Exec gets notified by something else - like the concat::fragment
+#     define
+# * Copies the file over to the final destination using a file resource
+#
+# === Aliases:
+#
+# * The exec can notified using Exec["concat_/path/to/file"] or
+#   Exec["concat_/path/to/directory"]
+# * The final file can be referened as File["/path/to/file"] or
+#   File["concat_/path/to/file"]
 #
-# ALIASES:
-#  - The exec can notified using Exec["concat_/path/to/file"] or
-#    Exec["concat_/path/to/directory"]
-#  - The final file can be referened as File["/path/to/file"] or
-#    File["concat_/path/to/file"]
 define concat(
   $path = $name,
   $owner = $::id,

manifests/setup.pp

@@ -1,17 +1,22 @@
+# === Class: concat::setup
+#
 # Sets up the concat system.
 #
-# $concatdir is where the fragments live and is set on the fact concat_basedir.
+# [$concatdir]
-# Since puppet should always manage files in $concatdir and they should
+#   is where the fragments live and is set on the fact concat_basedir.
-# not be deleted ever, /tmp is not an option.
+#   Since puppet should always manage files in $concatdir and they should
+#   not be deleted ever, /tmp is not an option.
 #
-# $puppetversion should be either 24 or 25 to enable a 24 compatible
+# [$puppetversion]
-# mode, in 24 mode you might see phantom notifies this is a side effect
+#   should be either 24 or 25 to enable a 24 compatible
-# of the method we use to clear the fragments directory.
+#   mode, in 24 mode you might see phantom notifies this is a side effect
+#   of the method we use to clear the fragments directory.
 #
 # The regular expression below will try to figure out your puppet version
 # but this code will only work in 0.24.8 and newer.
 #
 # It also copies out the concatfragments.sh file to ${concatdir}/bin
+#
 class concat::setup {
   $id = $::id
   $root_group = $id ? {