puppet-retrospec 0.11.0 → 0.12.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4a46b9123ebdcbabc88aea95e6d9bf8bc4d8186e
-  data.tar.gz: d051e9b7a2e86b5a6260382b5ce41517a058d7d6
+  metadata.gz: 9ef0263824df8bfe64011c9a30ad1a8ef8fbf3de
+  data.tar.gz: 9ad09244dae7ae1ec2db249182d9986fef0ad812
 SHA512:
-  metadata.gz: ea9f08b9433abd1b92cbcc4ebef5e161acba887b78dc9048b442f308d4f210bf02a11936b3593edd55f94d0c4acc19b403a9e8b6f07f790dcdf911552db2684a
-  data.tar.gz: d55f442ff7e53df1b2736ea9fc493da6b1fdaca921f151402a0548b95327e2bb86e875772d04a9b325b3a90402912f7fd395f28130697f0a59b75e11bc09d8c1
+  metadata.gz: 1f5380eb28ffa6cc128c6c53c96ba8d77d0c6ff212d2bd30752fc5476539bd82efccc28efc6ed88632c352772a7f22675f186028bdbec9a7a9422735a5e7a3ef
+  data.tar.gz: 590a1a3f3eafc2fc621e8af7b335d47bf4eaec2e9b22491c3b17e8c9a5d33f03a700cb0bbbf257c610755afd25d6c94fcc2d6574f4e4aadc159422137fa432e2

data/.rubocop.yml

@@ -0,0 +1,17 @@
+AllCops:
+  Exclude:
+    - vendor/**/*
+    - pkg/**/*
+    - spec/fixtures/**/*
+
+# Configuration parameters: AllowURI, URISchemes.
+Metrics/LineLength:
+  Max: 128
+
+# dealbreaker:
+Style/TrailingComma:
+  Enabled: false
+
+# we still support ruby 1.8
+Style/HashSyntax:
+  Enabled: false

data/CHANGELOG.md

@@ -1,3 +1,14 @@
+## 0.12.0
+ * fix an annoying issue when creating new modules and current directory
+ * gh-38 - added ability to create new types and type unit tests
+ * gh-39 - add functionality to create new providers
+ * gh-40 - add ability to generate functions
+ * gh-43 - add ability to create kwalify schema files
+ * gh-42 - continue with creating files when retrospec parser fails on invalid code
+## 0.11.0
+ * gh-31 - add ability to generate new fact and spec tests
+ * add awesome_print gem
+ * gh-37 - move new module functionality to its own generator class 
 ## 0.10.0
  * refactor cli options to use retrospec 0.4.0 specifications
  * gh-32 - add ability to create new module

data/DEVELOPMENT.md

@@ -0,0 +1,3 @@
+# Development
+
+Coming soon

data/Gemfile

@@ -1,16 +1,17 @@
-source "http://rubygems.org"
+source 'http://rubygems.org'
 
 gem 'trollop'
-gem 'retrospec', "~> 0.4"
+gem 'retrospec', '~> 0.4'
 gem 'awesome_print'
+gem 'facets'
 # Include everything needed to run rake, tests, features, etc.
 group :development do
-  gem "rspec", "~> 3.2"
-  gem 'puppet', '3.7.3',  :path => 'vendor/gems/puppet-3.7.3'
-  gem "yard", "~> 0.7"
-  gem "rdoc", "~> 3.12"
-  gem "bundler", "~> 1.0"
-  gem "jeweler"
+  gem 'rspec', '~> 3.2'
+  gem 'puppet', '3.7.3', :path => 'vendor/gems/puppet-3.7.3'
+  gem 'yard', '~> 0.7'
+  gem 'rdoc', '~> 3.12'
+  gem 'bundler', '~> 1.0'
+  gem 'jeweler'
   gem 'pry'
-  gem "fakefs", :require => "fakefs/safe"
+  gem 'fakefs', :require => 'fakefs/safe'
 end

data/Gemfile.lock

@@ -17,6 +17,7 @@ GEM
     descendants_tracker (0.0.4)
       thread_safe (~> 0.3, >= 0.3.1)
     diff-lcs (1.2.5)
+    facets (3.0.0)
     facter (2.4.4)
       CFPropertyList (~> 2.2.6)
     fakefs (0.6.7)
@@ -94,6 +95,7 @@ PLATFORMS
 DEPENDENCIES
   awesome_print
   bundler (~> 1.0)
+  facets
   fakefs
   jeweler
   pry

data/README.md

@@ -1,95 +1,104 @@
-[![Gem Version](https://badge.fury.io/rb/puppet-retrospec.svg)](http://badge.fury.io/rb/puppet-retrospec)
-
 Puppet-Retrospec
 ================
+A retrospec plugin for puppet that generates puppet rspec test code based on the current code inside your module.
+
+Proper testing is hard especially when you are new to ruby, rspec or even puppet.
+
+Retrospec makes it dead simple to get started with advanced puppet module development.  Retrospec will scan you puppet module files and actually write some very basic rspec-puppet test code.  Thus this gem will retrofit your existing puppet module with everything needed to get going with puppet unit testing.  Additionally, retrospec will outfit your module with any file you can think of.  Say goodbye to repetitive module setup.
 
-Generates puppet rspec test code based on the classes and defines inside the manifests directory.  
-Aims to reduce most of the boilerplate coding with default test patterns and module setup.
+Not only will retrospec generate tests for you, it will also assist in creating many of the advanced puppet module files like custom facts, functions, types, providers and schemas, as well as their associated test files. It will even create the module from scratch if so desired.
 
-Retrospec makes it dead simple to get started with puppet module development and puppet unit testing.  
-When you run retrospec, retrospec will scan you puppet manifests and actually write some very basic rspec-puppet test code.
-Thus this gem will retrofit your existing puppet module with everything needed to get going with puppet unit testing.  
-Additionally, retrospec will outfit your module with any file you can think of.  Say goodbye to repetitive module setup.
+The project was named retrospec because there are many times when you need to retrofit your module with various things.
 
-The project was named retrospec because there are many times when you need to retrofit your module with spec tests.
+If you like this project, star it and tell people!
 
 Table of Contents
 =================
 
   * [Build Status](#build-status)
   * [News](#news)
-  * [Dependency](#dependency)
   * [Install](#install)
-  * [How to use](#how-to-use)
-  * [Config file](#config_file)
+  * [How to use](#usage)
+    * [Module Path](#module-path)
+    * [Command Line Help](#command-line-help)
+  * [Design Goals](#design-goals)
+  * [Using the Generators](#using-the-generators)
+    * [Auto spec file creation](#auto-spec-file-creation)
+    * [Creating a new puppet module](#creating-a-new-puppet-module)
+    * [Creating a new fact](#creating-a-new-fact)
+    * [Creating a new provider](#creating-a-new-provider)
+    * [Creating a new function](#creating-a-new-function)
+    * [Creating a new type](#creating-a-new-type)
+    * [Creating a schema file](#creating-a-new-module-schema-file)
+  * [Dependency](#dependency)
+  * [Enable Future Parser](#enabling-the-future-parser)
+  * [Configuration](#configuration)
   * [Example](#example)
   * [About the test suite](#about-the-test-suite)
   * [How Does it do this](#how-does-it-do-this)
-  * [Overriding the templates](#overriding-the-templates)
-  * [Adding New Templates](#adding-new-templates)
   * [Beaker Testing](#beaker-testing)
   * [Troubleshooting](#troubleshooting)
   * [Running Tests](#running-tests)
   * [Understanding Variable Resolution](#understanding-variable-resolution)
   * [Todo](#todo)
   * [Future Parser Support](#future-parser-support)
-  * [Support](#support)
+  * [Paid Support](#paid-support)
 
 TOC Created by [gh-md-toc](https://github.com/ekalinin/github-markdown-toc)
 
-Build Status
-============
+## Build Status
 [![Build Status](https://travis-ci.org/logicminds/puppet-retrospec.png)](https://travis-ci.org/logicminds/puppet-retrospec)
 [![Gem Version](https://badge.fury.io/rb/puppet-retrospec.svg)](http://badge.fury.io/rb/puppet-retrospec)
 
 ## News
-This gem has been converted to a retrospec plugin.  This means that this gem no longer contains a binary and instead
-depends on the retrospec framework.  The new way of using this gem is : `retrospec puppet`
-
-Because I found this gem to be so useful I figured I could make it automate other types of projects and generalized its 
-use case.  So now any project you create can have its development workflow automated with retrospec.
-
-More info: https://github.com/nwops/retrospec.git
+### 1-18-16
+A slew of new features has been added with the 0.12 update. If you already use retrospec to retrofit your modules, now you can use retrospec to generate some of the more advanced puppet module customizations such as:
 
-As a result you may have a conflict with the retrospec binary when installing this plugin, please allow the new retrospec
-binary to replace the old one.
+- custom facts
+- providers
+- custom types
+- functions (v3 and v4)
+- parameter schemas  
 
-```shell
-[puppet@puppetdev module]$ gem install puppet-retrospec
-Fetching: retrospec-0.3.0.gem (100%)
-retrospec's executable "retrospec" conflicts with puppet-retrospec
-Overwrite the executable? [yN]  y
-Successfully installed retrospec-0.3.0
-Fetching: puppet-retrospec-0.9.0.gem (100%)
-Successfully installed puppet-retrospec-0.9.0
-Parsing documentation for retrospec-0.3.0
-Installing ri documentation for retrospec-0.3.0
-Parsing documentation for puppet-retrospec-0.9.0
-Installing ri documentation for puppet-retrospec-0.9.0
-2 gems installed
+This has been a feature in the making since Puppetconf 2015.  I would have finished this sooner but was sucked in
+binge watching a bunch of Netflix shows.   Check out `retrospec puppet -h` for a list of all new subcommands.
 
-```
 
-## Dependency
-Retrospec relies heavily on the puppet 3.7.x codebase.  Because of this hard dependency the puppet gem is vendored into
-the library so there should not be conflicts with your existing puppet gem.
-  
 ## Install
 `gem install puppet-retrospec`  
 
 This will also install the retrospec framework that is required to use the plugin.
 
-## How to use
+## Usage
+The easiest way to get started using retrospec-puppet is to run `retrospec puppet`
+from within your module directory. Retrospec uses the current directory if no options
+are specified.  Expect to run `retrospec puppet` multiple times throughout the day.
+Retrospec will never overwrite a file, so if something already exists retrospec will
+skip the file. Many times you will find yourself deleting existing files and allowing retrospec to recreate them based on updated templates.
+
+### Module Path
+By default the module path is dynamically set based on the current directory.
+If you need to point to a directory outside the current directory you can use the `--module_path` option.  This option is built into the retrospec framework
+so be sure to use `retrospec -m path_to_module`.
 
-Run from the command line: `retrospec puppet`
+### Command Line Help
+There is a `-h` at every level of commands and subcommands.
+
+ - `retrospec -h`
+ - `retrospec puppet -h`
+ - `retrospec puppet <sub_command> -h`
 
-If you need to point to a directory outside the current directory you can use the `--module_path` option.
 ```
 [puppet@puppetdev ~]$ retrospec -m /tmp/test3323 puppet -h
 Generates puppet rspec test code based on the classes and defines inside the manifests directory.
 
 Subcommands:
 new_module
+new_fact
+new_type
+new_provider
+new_function
+
   -t, --template-dir=<s>        Path to templates directory (only for overriding Retrospec templates)
                                 (default: /Users/cosman/.retrospec/repos/retrospec-puppet-templates)
   -s, --scm-url=<s>             SCM url for retrospec templates (default:
@@ -103,76 +112,142 @@ new_module
   -h, --help                    Show this message  -h, --help                    Show this message
 ```
 
+## Design Goals
+One of the design goals of this plugin is to try to introspect as much information as possible so we don't need input from the user. If you are not sure what default values are used, use the `-h` option and the defaults will be revealed. Most of the defaults are dynamic.  
 
-### Enabling the future parser
-                     
-`retrospec -m ~/projects/puppet_modules/apache puppet --enable-future-parser`
+Another design goal is to allow the user to configure every option, so that passing
+additional options is not required when configured correctly.  Please see the [Configuration Section](#configuration) for setting a config file.
+
+## Using the Generators
+At this time the generators are limited to just creating facts, providers, types, functions and schemas. As time goes on I envision more complicated puppet customizations like faces, indirectors, reports, or whatever else the community deems important.
 
-### Creating a new module
+*Note:* the unit tests files created are only meant to get you started. Be aware that these unit test templates are not perfect and will need further refinement. Testing in this area is not well documented so its based of my own experience and imperfect.  Please submit a PR if you find ways to improve these [templates](https://github.com/nwops/retrospec-templates).  
 
-Creating a new module can now be done with retrospec as of 0.10.0. To do so you just need to use the sub command
-`new_module`.  See `retrospec puppet -h` for more options and overridable configurations.
+### Auto spec file creation
+Each generator will also create associated test files by default without having to use the generator command.  So if there is a existing module without tests for one of these things, retrospec will create the test files automatically. There is no need to run the generator subcommands to generate spec files for existing puppet module ruby files.  
 
+### Creating a new puppet module
+You can create a puppet module from scratch using retrospec.
+This can be compared to using `puppet module generate` with a skeleton. Retrospec
+differs slightly in that you can specify which skeleton/templates to use at creation time.  This is helpful when working with different clients or puppet versions.
+Unlike `puppet module generate` retrospec does not force you to create a
+directory with a namespace.  This means you do not need to rename anything after creating it. By default retrospec will consult the retrospec config file for default settings which can be overridden on the command line.  Having the config in place can save you a few key strokes.
 
 ```
-retrospec -m /tmp/new_module puppet new_module --namespace lmc --name apache2
-Successfully ran hook: /Users/cosman/.retrospec/repos/retrospec-puppet-templates/clone-hook
-Already up-to-date.
-
-The module located at: /tmp/new_module does not exist, do you wish to create it? (y/n): y
- + /tmp/new_module/manifests/
- + /tmp/new_module/manifests/init.pp
-Successfully ran hook: /Users/cosman/.retrospec/repos/retrospec-puppet-templates/pre-hook
-
- + /tmp/new_module/.bundle/
- + /tmp/new_module/.bundle/config
- + /tmp/new_module/.fixtures.yml
- + /tmp/new_module/.git/
- + /tmp/new_module/.git/hooks/
- + /tmp/new_module/.git/hooks/pre-commit
- + /tmp/new_module/.gitignore
- + /tmp/new_module/.puppet-lint.rc
- + /tmp/new_module/.travis.yml
- + /tmp/new_module/Gemfile
- + /tmp/new_module/README.markdown
- + /tmp/new_module/Rakefile
- + /tmp/new_module/Vagrantfile
- + /tmp/new_module/spec/
- + /tmp/new_module/spec/acceptance/
- + /tmp/new_module/spec/shared_contexts.rb
- + /tmp/new_module/spec/spec_helper.rb
- + /tmp/new_module/metadata.json
- + /tmp/new_module/spec/classes/
- + /tmp/new_module/spec/classes/apache2_spec.rb
+# use -m to specify the module path
+retrospec -m /tmp/test_module_123 puppet new_module -n lmc-test123
+# or without specifying module_path
+cd /tmp/modules
+export RETROSPEC_PUPPET_AUTO_GENERATE=true
+retrospec puppet new_module -n lmc-test124
+ + /private/tmp/modules/lmc-test124/manifests/
+ + /private/tmp/modules/lmc-test124/manifests/init.pp  
+ + /private/tmp/modules/lmc-test124/metadata.json
+```
+
+### Creating a new fact
+Creating a new fact is easy with retrospec. Just use the following to
+create a fact and unit test.
+```
+retrospec -m /tmp/test_module_123 puppet new_fact -n datacenter
+Successfully ran hook: /Users/cosman/github/retrospec-templates/clone-hook
+ + /private/tmp/modules/test123/lib/facter/
+ + /private/tmp/modules/test123/lib/facter/datacenter.rb
+ + /private/tmp/modules/test123/spec/unit/facter/
+ + /private/tmp/modules/test123/spec/unit/facter/datacenter_spec.rb
+```
+
+### Creating a new provider
+Create a new provider is easy.  Just specify the puppet type you want the generator
+to use and the stub code for a provider and provider test file will be created.
+
+```
+cd testabc124
+retrospec puppet new_provider -t package -n ibm_pkg
+Successfully ran hook: /Users/user1/retrospec-templates/clone-hook
+
+ + /tmp/testabc124/lib/puppet/provider/package/
+ + /tmp/testabc124/lib/puppet/provider/package/ibm_pkg.rb
+Successfully ran hook: /Users/user1/retrospec-templates/pre-hook
+```
+### Creating a new function
+Creating a new function is just as easy as other generators. Use the new_function
+sub command and specify the name.  Specify `--type v4` if you wish to create
+a new 'v4' function, otherwise v3 is the default. Since testing functions
+can be done in both rspec-ruby and rspec-puppet you can specify the test type as
+well and retrospec will default to `rspec-puppet`.
+
+```
+cd testabc124
+retrospec puppet new_function -n is_url
+Successfully ran hook: /Users/user1/retrospec-templates/clone-hook
++ /private/tmp/testabc124/lib/puppet/parser/functions/
++ /private/tmp/testabc124/lib/puppet/parser/functions/is_url.rb
+```
 
+### Creating a new type
+Creating a type is similar to any other generator. You can specify which parameters,
+properties, and providers to generate. Retrospec will generate a default provider
+if none are specified.
+
+```
+retrospec puppet new_type -n test_type --parameters param1 param2 --properties prop1 prop2 --providers default
+Successfully ran hook: /Users/user1/retrospec-templates/clone-hook
+
+ + /private/tmp/testabc124/lib/puppet/type/
+ + /private/tmp/testabc124/lib/puppet/type/test_type.rb
+ + /private/tmp/testabc124/lib/puppet/provider/test_type/
+ + /private/tmp/testabc124/lib/puppet/provider/test_type/default.rb
+Successfully ran hook: /Users/user1/retrospec-templates/pre-hook
 ```
+### Creating a new module schema file
+Schema files are something I came up with recently and something I have found useful for various things. These schema files map all the puppet parameters in the classes and defines you have inside your module. You can use these schema files for validating hiera, generating documentation, or to serve as parameter documentation.  At this time the generator map only known datatypes so its up to you to define some of the complex data structures you have for puppet parameters.
+Maintaining a schema file is optional, but is incredible useful for people using your module and validating hiera data. Schema files are generated by default with every `retrospec puppet` run.
 
-## Config file
-Previously before release 0.9.0 there was no way to set a config file so you were stuck with always 
-having to pass in the same cli options. With the 0.9.0 release we now rely on the retrospec framework which
-gives us access to config file options for free. Below is a list of options that you can set
-in the config file.  (/Users/username/.retrospec/config.yaml)  `retrospec -h`
+```
+cd testabc124
+retrospec puppet
++ /private/tmp/testabc124/testabc124_schema.yaml
+```
+
+## Dependency
+Retrospec relies heavily on the puppet 3.7.x codebase.  Because of this hard dependency the puppet gem is vendored into the library so there should not be conflicts with your existing puppet gem.  
+
+## Enabling the future parser
+
+`retrospec -m ~/projects/puppet_modules/apache puppet --enable-future-parser`
+
+Please see #future-parser-support for why this might be required.
+
+## Configuration
+ Below is a list of options that you can set in the config file.  Setting these options will help cut down on passing parameters. (/Users/username/.retrospec/config.yaml)  `retrospec -h`
+
+ *Note:* if might be useful to have several config files for different clients or
+ situations where you want to easily swap out templates or options.
+ `retrospec --config-map /Users/user1/.retrospec/client1.yaml`
 
 ```yaml
+# used by the main puppet plugin and every subcommand
 plugins::puppet::templates::url: https://github.com/nwops/retrospec-templates
 plugins::puppet::templates::ref: master
 plugins::puppet::enable_beaker_tests: true
 plugins::puppet::enable_future_parser: true
 plugins::puppet::template_dir: /Users/username/.retrospec/repos/retrospec-puppet-templates
+# used when creating new modules
 plugins::puppet::namespace: organization
+plugins::puppet::default_license: 'Apache-2.0'
 plugins::puppet::author: your_name
+# used when creating new functions
+plugins::puppet::default_function_version: v3
+plugins::puppet::default_function_test_type: rspec
+
+
 ```
-Note: your not required to set any of these as they can be specified on the cli and also default to 
-sane values.
 
-Example
-======================
+*Note:* your not required to set any of these as they can be specified on the cli and also default to reasonable values.
 
-Below you can see that it creates files for every resource in the apache module in addition to other files
-that you need for unit testing puppet code. Rspec-puppet best practices says to put definitions in a defines folder
-and classes in a classes folder since it infers what kind of resource it is based on this convention.  Retrospec sets up
-this scaffolding for you.  Don't like the files that came with your module?  Simply delete the files and re-generate them
-with retrospec.
+## Example
+Below you can see that it creates files for every resource in the apache module in addition to other files that you need for unit testing puppet code. Rspec-puppet best practices says to put definitions in a defines folder and classes in a classes folder since it infers what kind of resource it is based on this convention.  Retrospec sets up this scaffolding for you.  Don't like the files that came with your module?  Simply delete the files and regenerate them with `puppet retrospec`.
 
 ```shell
 $ pwd
@@ -190,37 +265,19 @@ $ retrospec puppet
   + /Users/cosman/github/puppetlabs-apache/spec/classes/default_mods_spec.rb
   + /Users/cosman/github/puppetlabs-apache/spec/classes/dev_spec.rb
   + /Users/cosman/github/puppetlabs-apache/spec/classes/mod/disk_cache_spec.rb
-  + /Users/cosman/github/puppetlabs-apache/spec/classes/mod/fcgid_spec.rb
-  + /Users/cosman/github/puppetlabs-apache/spec/classes/mod/headers_spec.rb
-  + /Users/cosman/github/puppetlabs-apache/spec/classes/mod/info_spec.rb
-  + /Users/cosman/github/puppetlabs-apache/spec/classes/mod/itk_spec.rb
-  + /Users/cosman/github/puppetlabs-apache/spec/classes/mod/ldap_spec.rb
-  + /Users/cosman/github/puppetlabs-apache/spec/classes/mod/mime_spec.rb
-  + /Users/cosman/github/puppetlabs-apache/spec/classes/php_spec.rb
-  + /Users/cosman/github/puppetlabs-apache/spec/classes/proxy_spec.rb
-  + /Users/cosman/github/puppetlabs-apache/spec/classes/python_spec.rb
   + /Users/cosman/github/puppetlabs-apache/spec/classes/service_spec.rb
   + /Users/cosman/github/puppetlabs-apache/spec/classes/ssl_spec.rb
   + /Users/cosman/github/puppetlabs-apache/spec/defines/
   + /Users/cosman/github/puppetlabs-apache/spec/defines/balancer_spec.rb
   + /Users/cosman/github/puppetlabs-apache/spec/defines/balancermember_spec.rb
-  + /Users/cosman/github/puppetlabs-apache/spec/defines/default_mods/
-  + /Users/cosman/github/puppetlabs-apache/spec/defines/default_mods/load_spec.rb
-  + /Users/cosman/github/puppetlabs-apache/spec/defines/listen_spec.rb
-  + /Users/cosman/github/puppetlabs-apache/spec/defines/mod_spec.rb
-  + /Users/cosman/github/puppetlabs-apache/spec/defines/namevirtualhost_spec.rb
   + /Users/cosman/github/puppetlabs-apache/spec/defines/vhost_spec.rb
- 
+
 ```
 
-Looking at the file we can see that it did a lot of work for us.  Retrospec generated many tests automatically.
-However the variable resolution isn't perfect so you will need to manually resolve some variables.  This doesn't produce
-100% coverage but all you did was pressed enter to produce all this anyways.
-Below is the classes/apache_spec.rb file.  Notice that while Retrospec created all these files, you still need to do more work.
-Retrospec is only here to setup your module for testing, which might save you several hours each time you create a module.
-Below I'll go through the different parts of automation that you can use in your testing.
+Looking at the file we can see that it did a lot of work for us.  Retrospec generated many tests automatically. However the variable resolution isn't perfect so you will need to manually resolve some variables.  This doesn't produce 100% coverage but all you did was press enter to produce all this anyways. Below is the classes/apache_spec.rb file.  Notice that while Retrospec created all these files, you still need to do more work.
+Retrospec is only here to setup your module for testing, which might save you several hours each time you create a module. Below I'll go through the different parts of automation that you can use in your testing.
+
 
-   
 ```ruby
 require 'spec_helper'
 require 'shared_contexts'
@@ -392,16 +449,11 @@ end
 
 ```
 
-About the test suite
-======================
-At this time the test suite that is automatically generated is very basic.  Essentially it just creates a test for every
-resource not in a code block with the exception of conditional code blocks.  While this might be all you need, the more
-complex your code is the less retrospec will generate until further improvements to the generator are made.
+## About the test suite
+At this time the test suite that is automatically generated is very basic.  Essentially it just creates a test for every resource not in a code block with the exception of conditional code blocks.  While this might be all you need, the more complex your code is the less retrospec will generate until further improvements to the generator are made.
+
 However, one of the major stumbling blocks is just constructing everything in the spec
-directory which retrospec does for you automatically.  Its now up to you to further enhance your test suite with more
-tests and conditional logic using describe blocks and such.  You will notice that some variables are not resolved.
-Currently this is a limitation that I hope to overcome, but until now its up to you to manually resolve those variables
-prefixed with a '$'.
+directory which retrospec does for you automatically.  Its now up to you to further enhance your test suite with more tests and conditional logic using describe blocks and such.  You will notice that some variables are not resolved. Currently this is a limitation that I hope to overcome, but until now its up to you to manually resolve those variables prefixed with a '$'.
 
 Example:
 
@@ -419,134 +471,42 @@ For now you will probably want to read up on the following documentation:
 * [Puppet spec helper](https://github.com/puppetlabs/puppetlabs_spec_helper/blob/master/README.markdown)
 
 
-How Does it do this
-=======================
-Basically Retrospec uses the puppet lexer and parser to scan your code in order to fill out some basic templates that will retrofit
-your puppet module with unit tests.  Currently I rely on the old AST parser to generate all this.  This is why puppet 3.7
-is vendored into the gem.
-
-Overriding the Templates
-=======================
-There may be a time when you want to override the default templates used to generate the rspec related files.
-By default retrospec will clone these [templates](https://github.com/nwops/retrospec-templates)
-and place inside the default or specified template directory.  Previously the templates were kept inside the gem
-and cloning was not required. However, after using retrospec for a few months it makes more sense to keep these templates
-versioned controlled in their own repo and update them before each retrospec use.  This also makes it easy for team
-contributions to be spread to other team members quickly.
-  
+## How Does it do this
+Basically Retrospec uses the puppet lexer and parser to scan your code in order to fill out some basic templates that will retrofit your puppet module with unit tests.  Currently I rely on the old AST parser to generate all this.  This is why puppet 3.7 is vendored into the gem.
+
+## Overriding the Templates
+There may be a time when you want to override the default templates used to generate the rspec related files. By default retrospec will clone these [templates](https://github.com/nwops/retrospec-templates) and place inside the default or specified template directory.  
+
 ```shell
-    -t, --template-dir=<s>  Path to templates directory (only for overriding Retrospec templates) (default: /Users/user1/.retrospec/repos/retrospec-puppet-templates)
-    -s, --scm-url=<s>       SCM url for retrospec templates
-    -b, --branch=<s>        Branch you want to use for the retrospec template repo
+-t, --template-dir=<s>        Path to templates directory (only for overriding Retrospec templates) (default: /Users/cosman/github/retrospec-templates)
+-s, --scm-url=<s>             SCM url for retrospec templates (default: git@github.com:nwops/retrospec-templates.git)
+-b, --branch=<s>              Branch you want to use for the retrospec template repo (default: master)
 
 ```
 
 ### Environment variables to set template defaults
-
 RETROSPEC_PUPPET_SCM_URL  # set this to auto set your scm url to the templates
 RETROSPEC_PUPPET_SCM_BRANCH # set this to auto checkout a particular branch (only works upon initial checkout)
 
-After running retrospec, retrospec will clone the templates from the default template url or from whatever you set to the templates path.  
-If you have already created the erb file in the templates location, then retrospec will not overwrite the file as there will
-be a SCM conflict.
-You can use multiple template paths if you use them for different projects so just be sure the set the correct
-template option when running retrospec.  `retrospec -t`
+After running retrospec, retrospec will clone the templates from the default template url or from whatever you set to the templates path.  If you have already created the erb file in the templates location, then retrospec will not overwrite the file as there will be a SCM conflict. You can use multiple template paths if you use them for different projects so just be sure the set the correct template option when running retrospec.  `retrospec -t`
 
-The default user location for the templates when not using `retrospec -t` variable is ~/.retrospec_templates
+The default user location for the templates when not using `retrospec -t` variable is ~/.retrospec/repos/retrospec-puppet-templates
 
 Example:
 `--template-dir=~/my_templates`
 
-As I said above some of us need different templates for different projects and so I have outlined a simple scenario below:
-Lets say I have three clients that each need site specific files in the module and the default templates just 
-don't give me everything I want.  Thus I will need to override the templates for each client.
-
-```shell
-    retrospec puppet --template-dir ~/retrspec_client1
-    retrospec puppet --template-dir ~/retrspec_client2
-    retrospec puppet --template-dir ~/retrspec_client3
-    touch ~/retrspec_client1/module_files/special_file_for_client1.yml
-    touch ~/retrspec_client2/module_files/special_file_for_client2.yml
-    touch ~/retrspec_client3/module_files/special_file_for_client3.yml
-
-    mkdir -p ~/{client1,client2, client3}
-    cd ~/client1 && puppet module generate lmc-module1
-    cd ~/client2 && puppet module generate lmc-module1
-    cd ~/client3 && puppet module generate lmc-module1
-
-    cd ~/client1/module1 && retrospec --template-dir ~/retrspec_client1
-    cd ~/client2/module1 && retrospec --template-dir ~/retrspec_client2
-    cd ~/client3/module1 && retrospec --template-dir ~/retrspec_client3
-```
-Now when you run retrospec just pass in the template path for the specified client and the files will be created as you 
-specified in each clients template directory.
-
-Adding New Templates
-======================
-Should you ever need to add new templates or normal files of any kind retrospec will automatically render and copy the template file
-to the module path if you place a file inside the `template_path/module_files` directory.  The cool thing about this feature
-is that retrospec will recursively create the same directory structure you make inside the `module_files` directory inside your
-module.  Files do not need to end in .erb will still be rendered as a erb template.  Symlinks will be preserved and not 
-dereferenced. 
-
-This follows the convention over configuration pattern so no directory name or filename is required when running retrospec.
-Just put the template file in the directory where you want it (under module_files) and name it exactly how you want it to appear in the module and retrospec
-will take care of the rest.  Please note that any file ending in .erb will have this extension automatically removed.
-
-Example:
-So lets say you want to add a .gitlab-ci.yaml file to all of your modules in your modules directory.  
-
-```shell
-   touch ~/.retrospec_templates/module_files/.gitlab-ci.yaml
-   
-   tree ~/.retrospec_templates -a
-   ./.retrospec_templates
-   ├── acceptance_spec_test.erb
-   ├── module_files
-   │   ├── .fixtures.yml
-   │   ├── .gitignore.erb
-   │   ├── .gitlab-ci.yaml
-   │   ├── .travis.yml
-   │   ├── Gemfile
-   │   ├── README.markdown
-   │   ├── Rakefile
-   │   ├── Vagrantfile
-   │   └── spec
-   │       ├── acceptance
-   │       │   └── nodesets
-   │       │       └── ubuntu-server-1404-x64.yml
-   │       ├── shared_contexts.rb
-   │       ├── spec_helper.rb
-   │       └── spec_helper_acceptance.rb
-   └── resource_spec_file.erb
-
-    for dir in ../modules/*; do
-       name=`basename $dir`
-       retrospec -m $dir -e
-       + /Users/user1/modules/module1/.gitlab-ci.yaml
-    done
-
-```
-
-Beaker Testing
-=================
-Beaker is Puppetlabs acceptance testing framework that you use to test puppet code on real machines.  Beaker is fairly new
-and is subject to frequent changes.  Testing patterns have not been established yet so consider beaker support in puppet-retrospec
+## Beaker Testing
+Beaker is Puppetlabs acceptance testing framework that you use to test puppet code on real machines.  Beaker is fairly new and is subject to frequent changes.  Testing patterns have not been established yet so consider beaker support in puppet-retrospec
 to be experimental.
 
-If you wish to enable the creation of beaker tests you can use the following cli option.  By default these
-acceptance tests are not created.  However at a later time they will be enabled by default.
+If you wish to enable the creation of beaker tests you can use the following cli option.  By default these acceptance tests are not created.  However at a later time they will be enabled by default.
 
 `--enable-beaker-tests`
 
-I am no expert in Beaker so if you see an issue with the templates, acceptance_spec_helper or other workflow, please issue
-a PR.
+I am no expert in Beaker so if you see an issue with the templates, acceptance_spec_helper or other workflow, please issue a PR.
 
-Troubleshooting
-===============
-If you see the following, this error means that you need to add a fixture to the fixtures file.
-At this time I have no idea what your module requires.  So just add the module that this class belongs to 
-in the .fixtures file.
+## Troubleshooting
+If you see the following, this error means that you need to add a fixture to the fixtures file. At this time I have no idea what your module requires.  So just add the module that this class belongs to in the .fixtures file.
 
 See [fixtures doc](https://github.com/puppetlabs/puppetlabs_spec_helper#using-fixtures) for more information
 
@@ -558,8 +518,7 @@ See [fixtures doc](https://github.com/puppetlabs/puppetlabs_spec_helper#using-fi
      # ./spec/defines/instance/source_spec.rb:34:in `block (2 levels) in <top (required)>'
 ```
 
-If you see something like the following, this means your current module is using a much older version of Rspec.  Retrospec
-uses Rspec 3 syntax so you need to update your rspec version.  If you have tests that using older rspec syntax, take a look
+If you see something like the following, this means your current module is using a much older version of Rspec.  Retrospec uses Rspec 3 syntax so you need to update your rspec version.  If you have tests that using older rspec syntax, take a look
 at [transpec](https://github.com/yujinakayama/transpec)
 
 ```shell
@@ -571,18 +530,14 @@ at [transpec](https://github.com/yujinakayama/transpec)
 
 ```
 
-If your tests will not run after running retrospec. Your spec_helper, Rakefile and Gemfile may not be compatible 
-with the pre-defined templates.  Just delete these files and re-run retrospec to recreate them.  Add back any modifications
-you might have had.
+If your tests will not run after running retrospec. Your spec_helper, Rakefile and Gemfile may not be compatible with the pre-defined templates.  Just delete these files and re-run retrospec to recreate them.  Add back any modifications you might have had.
 
-Running Retrospec Tests
-=============
-Puppet-retrospec tests its code against real modules downloaded directly from puppet forge. 
-We also do a little mocking as well but for the majority of the tests we download are 'fixtures'.
+## Running Retrospec Tests
+Puppet-retrospec tests its code against real modules downloaded directly from puppet forge.
 
 To run a clean test suite and re-download you must run with environment variable set
 ```
-RETROSPEC_CLEAN_UP_TEST_MODULES=true bundle exec rake spec 
+RETROSPEC_CLEAN_UP_TEST_MODULES=true bundle exec rake spec
 ```
 
 Otherwise to save time we skip the removal of test puppet modules therefore we don't re-download
@@ -590,29 +545,21 @@ Otherwise to save time we skip the removal of test puppet modules therefore we d
 bundle exec rake spec
 ```
 
-Understanding Variable Resolution
-=============
-I do my best to try and resolve all the variables.  Because the code does not rely on catalog compilation we have to
-build our own scope through non trival methods.  Some variables will get resolved while others will not.  As this code
-progresses we might find a better way at resolving variables.  For now, some variable will require manual interpolation.
+## Understanding Variable Resolution
+Because the code does not rely on catalog compilation we have to build our own scope through non trival methods.  Some variables will get resolved while others will not.  As this project progresses we might find a better way at resolving variables.  For now, some variable will require manual interpolation.
 
-Resolution workflow.
+### Variable Resolution workflow.
 
 1. load code in parser and find all parameters. Store these parameter values.
 2. Find all vardef objects, resolve them if possible and store the values
 3. Anything contained in a block of code is currently ignored, until later refinement.
 
-Future Parser Support
-==============
-Currently Retrospec uses the old/current AST parser for code parsing.  If your code contains future parser syntax
-the current parser will fail to render some resource definitions but will still render the spec file template without parameters
+##Future Parser Support
+Currently Retrospec uses the old/current AST parser for code parsing.  If your code contains future parser syntax the current parser will fail to render some resource definitions but will still render the spec file template without parameters
 and resource tests that are contained in your manifest. Retrospec is still extremely useful with Puppet 4.
+
 Since Puppet 4 introduces many new things and breaks many other things  I am not sure
-which side of the grass is greener at this time.  What I do know is that most people are using Puppet 3 and it may take
-time to move to Puppet 4.  I would suspect Retrospec would be more valuable for those moving to Puppet 4
-who don't have unit tests that currently have Puppet 3 codebases.  For those with a clean slate and start directly in
-Puppet 4, Retrospec will still be able to produce the templates but some of the test cases will be missing if the old AST
-parser cannot read future code syntax.  If your puppet 4 codebase is compatible with puppet 3 syntax there should not be an issue.
+which side of the grass is greener at this time.  What I do know is that most people are using Puppet 3 and it may take time to move to Puppet 4.  I would suspect Retrospec would be more valuable for those moving to Puppet 4 who don't have unit tests that currently have Puppet 3 codebases.  For those with a clean slate and start directly in Puppet 4, Retrospec will still be able to produce the templates but some of the test cases will be missing if the old AST parser cannot read future code syntax.  If your puppet 4 codebase is compatible with puppet 3 syntax there should not be an issue.
 
 In order to allow future parser validation please run retrospec with the following option.
 
@@ -621,18 +568,9 @@ In order to allow future parser validation please run retrospec with the followi
 
  ```
 
-Todo
-============
-- Add support to fill out used facts in the unit tests automatically
-- Add describe blocks around conditions in test code that change the catalog compilation
-- Auto add dependencies to fixtures file
-- Show a diff of the test file when retrospec is run multiple times and the test file is already created.
-
-Ruby Support
-============
+##Ruby Support
 Currently this library only supports ruby >= 1.9.3.  It might work on 1.8.7 but I won't support if it fails.
 
-Paid Support
-============
+##Paid Support
 Want to see new features developed much faster?  Contact me about a support contract so I can develop this tool during
-the day instead of after work.  contact: sales@logicminds.biz
+the day instead of after work.  contact: corey@nwops.io