Merge pull request #81 from danzilio/tasks

Adding tasks to automate building GitHub pages from strings docs

README.md

@@ -191,7 +191,7 @@ Here are a few other good resources for getting started with documentation:
 Rake Tasks
 -----
 
-This module is also available as a Gem and makes two rake tasks (`strings:generate` and `strings: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`:
+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`:
 
 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.
 
@@ -219,6 +219,15 @@ PuppetStrings::RakeTasks::Generate.new(:documentation) do |task|
 end
 ```
 
+The `strings:gh_pages` task will generate your 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 `-f` 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 keep this in mind as it **will be destructive** if not used properly.
+
 Developing and Contributing
 -----
 

lib/puppet-strings/rake_tasks.rb

@@ -15,4 +15,44 @@ namespace :strings do
   task :serve do
     PuppetX::PuppetLabs::Strings::Util.serve
   end
+
+  namespace :gh_pages do
+    git_uri = `git config --get remote.origin.url`.strip
+
+    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 reset --hard origin/gh-pages'
+          system 'git pull origin gh-pages'
+        end
+      else
+        Dir.mkdir('doc')
+        Dir.chdir('doc') do
+          system 'git init'
+          system "git remote add origin #{git_uri}"
+          system 'git pull'
+          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