First pass at wraith, update contribute and readme

Rachel · Rachel · commit 958c1974a200 · 2015-12-11T09:02:18.000-06:00
- Create wraith.yaml
 - Compare live and local docs
 - Include path for one of every content type
- Revise Rakefile so that wraith can be individually executed, default task is htmlproofer for circle
- gitignore the shots directory (images and galleries generated by wraith)
- Edit contribute to align with readme recommendation on building locally
 - Include steps to run tests indvidually (noted as optional)
 - Preserve instructions for editing on GH and link to GH doc
- Fix readme ol synstax
diff --git a/.gitignore b/.gitignore
@@ -13,3 +13,4 @@ composer.phar
 node_modules
 .vagrant
 bin/*
+shots/
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -2,14 +2,6 @@
 
 Help us create relevant and useful content for developers like yourself. See something you'd like to add or change? We love pull requests!
 
-## Before You Start
-
-* If you don't have one already, sign up for a [GitHub account](https://github.com/signup/free).
-* Fork the pantheon-systems/documentation repository on GitHub.
-  Trying to edit or create a file in this repository will create your fork automatically.
-* [Clone your fork locally](https://help.github.com/articles/cloning-a-repository/).
-* Add our repo as a remote. `git remote add upstream git@github.com:pantheon-systems/documentation.git`.
-
 **NOTE**: All contributions must be licensed under [CC-BY-SA](https://creativecommons.org/licenses/by-sa/4.0/). Code snippet contributions must additionally be licensed under [The MIT License](http://opensource.org/licenses/MIT). You must have permission to contribute your work under these terms.
 
 ## Issues - Searching and Creating
@@ -27,12 +19,25 @@ Description: The document currently suggests using XYZ commands, but I get the f
 
 Add labels to issues by clicking the gear in the sidebar on the right. Labels are used to signify priority, category, and to help filter existing issues. For example, if a doc is incorrect, the label 'Doc Defect' should be applied.
 
-## Edit Existing Docs
+## Edit and Test Locally Using Vagrant
+
+**Note**: To preserve the accuracy of promised information throughout the docs, search the repository for links to sections that have been renamed and update accordingly.
+
+1. [Use Vagrant](https://github.com/pantheon-systems/documentation#option-1-use-vagrant-recommended) to run the docs site locally.
+2. Navigate to your local `documentation` repository and use `git checkout -b <new-branch-name>` to switch to a new branch.
+3. Edit/Create docs locally using your favorite text editor (e.g. [Atom](https://atom.io/)), then save the file changes.
+4. Verify modifications on the local site <http://docs.local:8000/docs>
+5. Test layout or code changes by running `vagrant ssh` and `cd /vagrant`, then execute the following tests individually (optional):
+ - `grunt`: [a11y](https://github.com/addyosmani/a11y) accessibility audits
+ - `rake config[wraith.yaml]`: [Wraith](https://github.com/BBC-News/wraith) visual regression tool
+ - `rake htmlproofer`: [HTML::Proofer](https://github.com/gjtorikian/html-proofer) HTML validation
+ - `bin/behat`: [Behat](https://github.com/Behat/Behat)
+ - `scripts/merge_conflicts.sh`: Look for merge conflicts.
+6. Commit changes and push to your fork. Issue pull-requests one document/issue at a time.
+
+## Edit on GitHub
 
-1. Search [open issues](https://github.com/pantheon-systems/documentation/issues) to make sure your isn't duplicated.
-2. Locally, cd to the `documentation` repository and use `git checkout -b <new-branch-name>` to switch to a new branch.
-3. Edit locally, commit changes, and push to your fork.
-4. To preserve the accuracy of promised information throughout the docs, search the repository for links to the revised section and update related articles accordingly.
+Trying to edit or create a file in this repository will create your fork automatically. Commit changes and issue pull-requests one document/issue at a time. For more information, see [Using Pull Requests](https://help.github.com/articles/using-pull-requests/).
 
 ## Keep your Local Updated with Master
 
diff --git a/README.md b/README.md
@@ -43,52 +43,52 @@ Fork and clone this repository. Issue pull-requests one document at a time.
 
 ### Option 2. Install manually
 1. Get composer:
-If you do not want to install composer globally, please refer to [getcomposer.org instuctions](https://getcomposer.org/doc/00-intro.md#installation-linux-unix-osx).
-
-Run the following command to install composer globally:  
-```
-curl -sS https://getcomposer.org/installer | php
-mv composer.phar /usr/local/bin/composer
-```
-
-**Note**: Run the `mv` command with sudo if it fails.  
-3. Install dependencies:  
-From within the `documentation` repo, run the following command to install all needed dependencies:  
-```
-composer install
-```  
-4. Start your local server:  
-If you do not want to install sculpin globally, you can use the following commands to start your local server:  
-```
-./vendor/bin/sculpin generate --server
-```  
-Visit your docs site at: <http://localhost:8000/docs>  
-
-In order to globally execute sculpin, run the following commands:  
-```
-curl -O https://download.sculpin.io/sculpin.phar
-sudo chmod +x sculpin.phar
-mv sculpin.phar /usr/local/bin/sculpin
-```
-
-Build sculpin and run a local instance:
-
-```
-sculpin generate --server
-```
-Visit your docs site at: <http://localhost:8000/docs>
-
-
-Finally, you can tell sculpin to watch the docs directory and automatically
-regenerate anything changed:
-```
-sculpin generate --server --watch
-```
-If you use --watch and see it constantly running, regenerating, drop --watch
-until you identify and resolve the problem.  
+ If you do not want to install composer globally, please refer to [getcomposer.org instuctions](https://getcomposer.org/doc/00-intro.md#installation-linux-unix-osx).
+
+ Run the following command to install composer globally:  
+ ```
+ curl -sS https://getcomposer.org/installer | php
+ mv composer.phar /usr/local/bin/composer
+ ```
+
+ **Note**: Run the `mv` command with sudo if it fails.  
+2. Install dependencies:  
+ From within the `documentation` repo, run the following command to install all needed dependencies:  
+ ```
+ composer install
+ ```  
+3. Start your local server:  
+ If you do not want to install sculpin globally, you can use the following commands to start your local server:  
+ ```
+ ./vendor/bin/sculpin generate --server
+ ```  
+ Visit your docs site at: <http://localhost:8000/docs>  
+
+ In order to globally execute sculpin, run the following commands:  
+ ```
+ curl -O https://download.sculpin.io/sculpin.phar
+ sudo chmod +x sculpin.phar
+ mv sculpin.phar /usr/local/bin/sculpin
+ ```
+
+ Build sculpin and run a local instance:
+
+ ```
+ sculpin generate --server
+ ```
+ Visit your docs site at: <http://localhost:8000/docs>
+
+
+ Finally, you can tell sculpin to watch the docs directory and automatically
+ regenerate anything changed:
+ ```
+ sculpin generate --server --watch
+ ```
+ If you use --watch and see it constantly running, regenerating, drop --watch
+ until you identify and resolve the problem.  
 5. Images  
-For images to render on your local environment you need to apply these commands from within the `documentation` directory:
-```
-$ cd output_dev
-$ ln -s ./ source
-```
+ For images to render on your local environment you need to apply these commands from within the `documentation` directory:
+ ```
+ $ cd output_dev
+ $ ln -s ./ source
+ ```
diff --git a/Rakefile b/Rakefile
@@ -1,9 +1,69 @@
 require 'html/proofer'
+require "wraith/save_images"
+require "wraith/crop"
+require "wraith/spider"
+require "wraith/folder"
+require "wraith/thumbnails"
+require "wraith/compare_images"
+require "wraith/gallery"
 
 task default: %w[htmlproofer]
-
+desc "Run htmlproofer"
 task :htmlproofer do
       HTML::Proofer.new("./output_prod", {
         :disable_external => true,
       }).run
 end
+
+@config = ("wraith.yaml")
+
+desc "Execute wraith on two sites with a config you specify"
+task :config, [:yaml] do |_t, custom|
+  custom.with_defaults(:yaml => "config")
+  @config = "#{custom[:yaml]}"
+  Rake::Task["wraithdefault"].invoke
+end
+
+task :wraithdefault => [:reset_shots_folder, :check_for_paths, :setup_folders, :save_images, :crop_images, :compare_images, :generate_thumbnails, :generate_gallery] do
+  puts "Done!"
+end
+
+task :reset_shots_folder do
+  reset = Wraith::FolderManager.new(@config)
+  reset.clear_shots_folder
+end
+
+task :setup_folders do
+  create = Wraith::FolderManager.new(@config)
+  create.create_folders
+end
+
+task :compare_images do
+  compare = Wraith::CompareImages.new(@config)
+  compare.compare_images
+end
+
+task :check_for_paths do
+  spider = Wraith::Spidering.new(@config)
+  spider.check_for_paths
+end
+
+task :save_images do
+  @save_images = Wraith::SaveImages.new(@config)
+  @save_images.save_images
+end
+
+task :crop_images do
+  crop = Wraith::CropImages.new(@config)
+  crop.crop_images
+end
+
+task :generate_thumbnails do
+  thumbs = Wraith::Thumbnails.new(@config)
+  thumbs.generate_thumbnails
+end
+
+task :generate_gallery do
+  gallery = Wraith::GalleryGenerator.new(@config, false)
+  gallery.generate_gallery
+end
diff --git a/wraith.yaml b/wraith.yaml
@@ -0,0 +1,58 @@
+# Add as many domains as necessary. Key will act as a label
+domains:
+  live:  "https://pantheon.io/docs"
+  local: "http://docs.local:8000/docs"
+
+# (optional) JavaScript file to execute before taking screenshot of every path.
+# Can be used to reload current page with headers specified, or to dynamically
+# AJAX in content, or all manner of other uses!
+#before_capture: 'javascript/global.js'
+
+# Type page URL paths below, here are a couple of examples.
+# They should exist for all of the domains you've specified above.
+paths:
+  home: /
+  article-index: /articles
+  single-article: /articles/going-live
+  subdir-index: /articles/local
+  guide-index: /guides
+  single-guide: /guides/visual-diff-with-wraith
+  changelog-index: /changelog
+  single-changelog: /changelog/2015-10-October
+
+# amount of fuzz ImageMagick will use when comparing images. A higher fuzz makes the comparison less strict.
+fuzz: '20%'
+
+# the maximum acceptable level of difference (in %) between two images.
+# Wraith considers it a failure if an image diff goes above this threshold.
+threshold: 5
+
+# screen widths (and optional height) to resize the browser to before taking the screenshot
+screen_widths:
+  - 320
+  - 600x768
+  - 768
+  - 1024
+  - 1280
+
+# the engine to run Wraith with. Examples: 'phantomjs', 'casperjs', 'slimerjs'
+browser: "casperjs"
+
+# the directory that your base screenshots will be stored in
+history_dir: 'shots_base'
+
+# the directory that your latest screenshots will be stored in
+directory: 'shots'
+
+gallery:
+  template: 'slideshow_template' # 'basic_template' (default)
+  thumb_width: 200
+  thumb_height: 200
+
+# choose how results are displayed in the gallery (default is `alphanumeric` if omitted)
+# Different screen widths are always grouped together.
+# Options:
+#   alphanumeric - all paths (with or without a difference) are shown, sorted by path
+#   diffs_first - all paths (with or without a difference) are shown, sorted by difference size (largest first)
+#   diffs_only - only paths with a difference are shown, sorted by difference size (largest first)
+mode: diffs_first
