(PDOC-63) Implement the Puppet Strings rake tasks.

This commit implements the `strings:generate` and `strings:gh_pages:update`
rake tasks.

The `strings:generate` task is responsible for generating Puppet Strings
documentation.

The `strings:gh_pages:update` task is responsible for updating the `gh_pages`
branch of a GitHub repository with the latest Puppet Strings documentation.

README.md

@@ -1,10 +1,9 @@
 Puppet Strings
-=============
+==============
 [![Build Status](https://travis-ci.org/puppetlabs/puppet-strings.png?branch=master)](https://travis-ci.org/puppetlabs/puppet-strings) [![Gem Version](https://badge.fury.io/rb/puppet-strings.svg)](https://badge.fury.io/rb/puppet-strings)
 
 A Puppet Face and plugin built on the [YARD Documentation Tool](http://yardoc.org/) and the Puppet 4 Parser. It is uses YARD and the Puppet Parser to generate HTML documentation about Puppet code and Puppet extensions written in Ruby. It will eventually replace the `puppet doc` command once feature parity has been achieved.
 
-
 |                |                                                             |
 | -------------- |------------------------------------------------------------ |
 | *Code*         | [GitHub][repo]                                              |
@@ -193,44 +192,51 @@ Here are a few other good resources for getting started with documentation:
   * [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 three rake tasks (`strings:generate`, `strings:serve`, and `strings:gh_pages`) available in `puppet-strings/rake_tasks`. To add this to your module's CI workflow, be sure to add this module to your `Gemfile`:
+Puppet Strings comes with two rake tasks: `strings:generate` and `strings:gh_pages:update` available in `puppet-strings/tasks`.
 
-In addition to generating the usual 'doc' directory of HTML documentation, the `strings:generate` rake task will also drop a strings.json file containing a JSON representation of the module into the directory the rake task was run from.
+Add the following to your Gemfile to use `puppet-strings`:
 
 ```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`:
+In your `Rakefile`, add the following to use the `puppet-strings` tasks:
 
 ```ruby
-require 'puppet-strings/rake_tasks'
+require 'puppet-strings/tasks'
 ```
 
-The task `strings:generate` which is provided by including `puppet-strings/rake_tasks` will scan the manifests and lib directory from your single module. If you need to document a complete, or part of a, puppet tree, you can use the `PuppetStrings::RakeTasks::Generate` task. This rake task will by default overwrite strings:generate unless you specify a custom name. See the example below on how you can use it and which options it supports.
+The `strings:generate` task can be used to generate documentation:
 
-```ruby
+```
-require 'puppet-strings/rake_tasks/generate'
+$ rake strings:generate
-
-PuppetStrings::RakeTasks::Generate.new(:documentation) do |task|
-  task.paths = ['site/roles','site/profiles','modules/internal']
-  task.excludes = ['/vendor/','/example/']
-  task.options = {} # disables the strings.json output
-  # module_resourcefiles are the patterns of included files. Below is the default.
-  # task.module_resourcefiles = ['manifests/**/*.pp', 'lib/**/*.rb']
-end
 ```
 
-The `strings:gh_pages` task will generate your Strings documentation to be made available via [GitHub Pages](https://pages.github.com/). It will:
+The task accepts the following parameters:
 
-  1. Create a `doc` directory in the root of your project
+* `patterns`: the search patterns to use for finding files to document (defaults to `manifests/**/*.pp functions/**/*.pp types/**/*.pp lib/**/*.rb`).
-  2. Check out the `gh-pages` branch of the current repository in the `doc` directory (it will create a branch if one does not already exist)
+* `debug`: enables debug output when set to `true`.
-  3. Generate strings documentation using the `strings:generate` task
+* `backtrace`: enables backtraces for errors when set to `true`.
-  4. Commit the changes and push them to the `gh-pages` branch **with the `-f` flag**
+* `markup`: the markup language to use (defaults to `markdown`).
+* `yard_args`: additional arguments to pass to YARD.
 
-This task aims to keep the `gh-pages` branch up to date with the current code and uses the `-f` flag when pushing to the `gh-pages` branch. Please keep this in mind as it **will be destructive** if not used properly.
+An example of passing arguments to the `strings:generate` Rake task:
+
+```
+$ rake strings:generate\['**/*.pp **/*.rb, true, true, markdown, --readme README.md']
+```
+
+The `strings:gh_pages:update` task will generate your Puppet Strings documentation to be made available via [GitHub Pages](https://pages.github.com/). It will:
+
+1. Create a `doc` directory in the root of your project
+2. Check out the `gh-pages` branch of the current repository in the `doc` directory (it will create a branch if one does not already exist)
+3. Generate strings documentation using the `strings:generate` task
+4. Commit the changes and push them to the `gh-pages` branch **with the `--force` flag**
+
+This task aims to keep the `gh-pages` branch up to date with the current code and uses the `-f` flag when pushing to the `gh-pages` branch.
+***Please note this operation will be destructive if not used properly.***
 
 Developing and Contributing
 -----

Rakefile

@@ -1,6 +1,10 @@
 require 'rubygems'
 require 'puppetlabs_spec_helper/rake_tasks'
 require 'puppet-lint/tasks/puppet-lint'
+
+# Add our own tasks
+require 'puppet-strings/tasks'
+
 PuppetLint.configuration.send('disable_80chars')
 PuppetLint.configuration.ignore_paths = ["spec/**/*.pp", "pkg/**/*.pp"]
 

lib/puppet-strings/tasks.rb

@@ -0,0 +1,10 @@
+require 'rake'
+require 'rake/tasklib'
+
+module PuppetStrings
+  # The module for Puppet Strings rake tasks.
+  module Tasks
+    require 'puppet-strings/tasks/generate.rb'
+    require 'puppet-strings/tasks/gh_pages.rb'
+  end
+end

lib/puppet-strings/tasks/generate.rb

@@ -0,0 +1,23 @@
+require 'puppet-strings'
+
+# Implements the strings:generate task.
+namespace :strings do
+  desc 'Generate Puppet documentation with YARD.'
+  task :generate, :patterns, :debug, :backtrace, :markup, :json, :yard_args do |t, args|
+    patterns = args[:patterns]
+    patterns = patterns.split if patterns
+    patterns ||= PuppetStrings::DEFAULT_SEARCH_PATTERNS
+
+    options = {
+      debug: args[:debug] == 'true',
+      backtrace: args[:backtrace] == 'true',
+      markup: args[:markup] || 'markdown',
+    }
+
+    options[:json] = args[:json] if args.key? :json
+    options[:yard_args] = args[:yard_args].split if args.key? :yard_args
+
+    PuppetStrings.generate(patterns, options)
+  end
+end
+

lib/puppet-strings/tasks/gh_pages.rb

@@ -0,0 +1,43 @@
+require 'puppet-strings/tasks'
+
+namespace :strings do
+  namespace :gh_pages do
+    desc 'Checkout the gh-pages branch for doc generation.'
+    task :checkout do
+      if Dir.exist?('doc')
+        fail "The 'doc' directory (#{File.expand_path('doc')}) is not a Git repository! Remove it and run the Rake task again." unless Dir.exist?('doc/.git')
+        Dir.chdir('doc') do
+          system 'git checkout gh-pages'
+          system 'git pull --rebase origin gh-pages'
+        end
+      else
+        git_uri = `git config --get remote.origin.url`.strip
+        fail "Could not determine the remote URL for origin: ensure the current directory is a Git repro with a remote named 'origin'." unless $?.success?
+
+        Dir.mkdir('doc')
+        Dir.chdir('doc') do
+          system 'git init'
+          system "git remote add origin #{git_uri}"
+          system 'git pull origin gh-pages'
+          system 'git checkout -b gh-pages'
+        end
+      end
+    end
+
+    desc 'Push new docs to GitHub.'
+    task :push do
+      Dir.chdir('doc') do
+        system 'git add .'
+        system "git commit -m '[strings] Generated Documentation Update'"
+        system 'git push origin gh-pages -f'
+      end
+    end
+
+    desc 'Run checkout, generate, and push tasks.'
+    task :update => [
+      :checkout,
+      :'strings:generate',
+      :push,
+    ]
+  end
+end