Merge pull request #7 from mnyrop/master

0.3.0

.gitignore

@@ -2,5 +2,5 @@
 Gemfile.lock
 build
 coverage
-_config.yml
-Rakefile
+doc
+.yardoc

.rubocop.yml

@@ -1,11 +1,20 @@
 AllCops:
+  TargetRubyVersion: 2.3
   Exclude:
     - 'spec/**/*'
 Metrics/LineLength:
+  IgnoredPatterns:
+    - 'raise'
+    - 'puts'
+    - 'ÈÉÊË'
+    - 'EEEE'
+Style/FrozenStringLiteralComment:
   Enabled: false
-Metrics/MethodLength:
-  Max: 15
-Style/StringLiterals:
+Style/RedundantSelf:
   Enabled: false
 Metrics/AbcSize:
   Max: 20
+Metrics/MethodLength:
+  Max: 15
+Style/DoubleNegation:
+  Enabled: false

.yardopts

@@ -0,0 +1 @@
+--output-dir ./docs

Gemfile

@@ -1,6 +1,8 @@
 source 'https://rubygems.org'
 gemspec
 
+# dev/test utilities
 gem 'diane', require: false
 gem 'rubocop', require: false
 gem 'simplecov', require: false
+gem 'yard', require: false

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 marii nyrop
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,31 +1,30 @@
-# wax_tasks
-[![Gem Version](https://badge.fury.io/rb/wax_tasks.svg)](https://badge.fury.io/rb/wax_tasks) ![Libraries.io for GitHub](https://img.shields.io/librariesio/github/mnyrop/wax_tasks.svg)
-[![Build Status](https://travis-ci.org/mnyrop/wax_tasks.svg?branch=rubocop)](https://travis-ci.org/mnyrop/wax_tasks) [![Maintainability](https://api.codeclimate.com/v1/badges/5974d49e115dadf9f8df/maintainability)](https://codeclimate.com/github/mnyrop/wax_tasks/maintainability) [![Test Coverage](https://api.codeclimate.com/v1/badges/5974d49e115dadf9f8df/test_coverage)](https://codeclimate.com/github/mnyrop/wax_tasks/test_coverage)
+# wax_tasks 🐝
+[![Gem Version](https://badge.fury.io/rb/wax_tasks.svg)](https://badge.fury.io/rb/wax_tasks) ![License](https://img.shields.io/badge/license-MIT-yellowgreen.svg) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](http://makeapullrequest.com) [![](http://img.shields.io/badge/docs-rdoc.info-blue.svg)](http://marii.info/wax_tasks/)
 
-#### A gem-packaged set of [Rake](https://ruby.github.io/rake/) tasks for creating minimal exhibitions with [Jekyll](https://jekyllrb.com/), [IIIF](http://iiif.io), and [ElasticLunr.js](http://elasticlunr.com/).
+[![Build Status](https://travis-ci.org/mnyrop/wax_tasks.svg?branch=rubocop)](https://travis-ci.org/mnyrop/wax_tasks) [![](https://img.shields.io/librariesio/github/mnyrop/wax_tasks.svg)](https://libraries.io/github/mnyrop/wax_tasks) [![Maintainability](https://api.codeclimate.com/v1/badges/5974d49e115dadf9f8df/maintainability)](https://codeclimate.com/github/mnyrop/wax_tasks/maintainability) [![Test Coverage](https://api.codeclimate.com/v1/badges/5974d49e115dadf9f8df/test_coverage)](https://codeclimate.com/github/mnyrop/wax_tasks/test_coverage) 
 
-Looking for a Jekyll theme that works with [wax_tasks]()? Check out [minicomp/wax](https://minicomp.github.io/wax/).
+__wax_tasks__ is gem-packaged set of [Rake](https://ruby.github.io/rake/) tasks for creating minimal exhibition sites with [Jekyll](https://jekyllrb.com/), [IIIF](http://iiif.io), and [ElasticLunr.js](http://elasticlunr.com/).
 
-<br>
-<img src="https://raw.githubusercontent.com/minicomp/wiki/master/docs/assets/wax_screen.gif">
+It can be used to generate collection markdown pages from a data file ([wax:pagemaster](#waxpagemaster)), generate a client-side search index ([wax:lunr](#waxlunr)), generate IIIF-compliant derivatives (both Image + Presentation API) from local image files ([wax:iiif](#waxiiif)), and more.
 
+Looking for a Jekyll theme that works with [wax_tasks]()? Check out [minicomp/wax](https://minicomp.github.io/wax/).
 
-#### Getting Started
-- [Prerequisites](#prerequisites)
-- [Installing](#installing)
+```sh
+--------------------------------------------------------------------
+NOTE >> wax_tasks is being developed rapidly. it will be relatively 
+        volatile leading up to the beta release (v0.5.0).
+--------------------------------------------------------------------
+```
 
-#### Running the tasks
-- [wax:pagemaster](#waxpagemaster)
-- [wax:lunr](#waxlunr)
-- [wax:iiif](#waxiiif)
-- [wax:test](#waxtest)
+<br>
+<img src="https://raw.githubusercontent.com/minicomp/wiki/master/docs/assets/wax_screen.gif"/>
 
 
 # Getting Started
 
 ## Prerequisites
 
-You'll need `Ruby >= 2.2` with `bundler` installed. Check your versions with:
+You'll need `Ruby >= 2.3` with `bundler` installed. Check your versions with:
 ```bash
 $ ruby -v
   ruby 2.4.2p198 (2017-09-14 revision 59899) [x86_64-darwin15]
@@ -38,15 +37,22 @@ To use the IIIF task, you will also need to have ImageMagick installed and funct
 ```bash
 $ convert -version
   Version: ImageMagick 6.9.9-20 Q16 x86_64 2017-10-15 http://www.imagemagick.org
-  Copyright: © 1999-2017 ImageMagick Studio LLC
+  Copyright: Š 1999-2017 ImageMagick Studio LLC
   License: http://www.imagemagick.org/script/license.php
   Features: Cipher DPC Modules
   Delegates (built-in): bzlib freetype jng jpeg ltdl lzma png tiff xml zlib
 ```
 
-## Installing
+Next, you'll need a Jekyll site. You can clone the [minicomp/wax demo site](https://github.com/minicomp/wax/) or start a site from scratch with:
+
+```sh
+$ gem install jekyll
+$ jekyll new wax && cd wax
+```
+
+## Installation
 
-Add `wax_tasks` to your Jekyll site's Gemfile:
+Add `wax_tasks` to your Jekyll site's `Gemfile`:
 
 ```ruby
 gem 'wax_tasks'
@@ -61,39 +67,17 @@ $ bundle install
 Create a `Rakefile` with the following:
 ```ruby
 spec = Gem::Specification.find_by_name 'wax_tasks'
-Dir.glob("#{spec.gem_dir}/lib/wax/tasks/*.rake").each { |r| load r }
+Dir.glob("#{spec.gem_dir}/lib/tasks/*.rake").each { |r| load r }
 ```
 
-# Running the Tasks
+# Usage
 
-After following the installation instructions above, you will have access to the rake tasks in your shell by running `$ bundle exec rake wax:taskname` in the root directory of your Jekyll site.
+After following the installation instructions above, you will have access to the Rake tasks in your shell by running `$ bundle exec rake wax:taskname` in the root directory of your Jekyll site.
 
+<br>
+<img src="https://media.giphy.com/media/e7OR7qbQjF2ocNVS7V/giphy.gif"/>
 
-## wax:pagemaster
-
-Takes a CSV or JSON file of collection metadata and generates a Markdown page for each record to a directory using a specified layout. [Read More](https://minicomp.github.io/wiki/#/wax/tasks/pagemaster?id=top).
-
-`$ bundle exec rake wax:pagemaster collection-name`
-
-## wax:lunr
-
-Generates a client-side JSON search index of your site for use with [ElasticLunr.js](http://elasticlunr.com/). [Read More](https://minicomp.github.io/wiki/#/wax/tasks/lunr?id=top).
-
-`$ bundle exec rake wax:lunr`
-
-## wax:iiif
-
-Takes a local directory of images and generates tiles and data that work with a IIIF compliant image viewer like [OpenSeaDragon](https://openseadragon.github.io/), [Mirador](http://projectmirador.org/), or [Leaflet IIIF](https://github.com/mejackreed/Leaflet-IIIF). [Read More](https://minicomp.github.io/wiki/#/wax/tasks/iiif?id=top).
-
-`$ bundle exec rake wax:iiif collection-name`
-
-## wax:test
-
-Runs [`htmlproofer`](https://github.com/gjtorikian/html-proofer) on your compiled site to look for broken links, HTML errors, and accessibility concerns. Runs [Rspec](http://rspec.info/) tests if a `.rspec` file is present. [Read More](https://minicomp.github.io/wiki/#/wax/tasks/test?id=top).
-
-`$ bundle exec rake wax:test`
-
-# Sample \_config.yml file:
+## Sample site `_config.yml` file:
 
 ```yaml
 # basic settings
@@ -104,7 +88,8 @@ baseurl: '/wax'
 
 # build settings
 permalink: pretty # optional, creates `/page/` link instead of `page.html` link
-collections_dir: false # optional, allows you to tidy up and keep collections (below) inside a directory (as of jekyll 3.7)
+collections_dir: '' # optional, allows you to tidy up and keep collections
+                       # (see below) inside a directory (as of jekyll 3.7)
 
 # wax collection settings
 collections:
@@ -113,16 +98,79 @@ collections:
     layout: iiif-image-page
     output: true # this must be true for your .md pages to be built to html!
     lunr_index:
-      content: false
-      fields: [title, artist, location, _date, object_type, current_location]
+      content: false # whether or not to index the markdown page content (below the YAML)
+      fields: # the metadata fields to index
+        - title
+        - artist
+        - location
+        - _date
+        - object_type
+        - current_location
     iiif:
       meta:
         label: title
         location: current_location
+        # in this example, `label` will be the metadata field in the IIIF manifest,
+        # and it will be populated by the `title` column from objects.csv;
+        # likewise, `location` will pull from the `current_location` field.
+```
+
+The above example includes a single collection `objects` that comprises:
+1. a CSV `source` file (`objects.csv`), and
+2. a directory of images files.
+
+__wax_tasks__ will expect to find the `source` file in the `_data` directory, i.e., at `_data/objects.csv`. It will also expect to find the source images in a directory named after the collection within `_data/iiif`, i.e., `_data/iiif/objects/*.jpg`. Some tasks will require you to invoke the collection by name, e.g., `$ bundle exec rake wax:pagemaster objects` and `$ bundle exec rake wax:iiif objects`.
+
+For more information on configuring Jekyll collections for __wax_tasks__, check out the [minicomp/wax wiki](https://minicomp.github.io/wiki/#/wax/) and <https://jekyllrb.com/docs/collections/>.
+
+## Running the tasks
+
+### wax:pagemaster
+
+Takes a CSV, JSON, or YAML file of collection metadata and generates a [markdown](https://daringfireball.net/projects/markdown/syntax) page for each record to a directory using a specified layout. [Read More](https://minicomp.github.io/wiki/#/wax/tasks/pagemaster?id=top).
+
+`$ bundle exec rake wax:pagemaster collection-name`
+
+### wax:lunr
+
+Generates a client-side JSON search index of your site for use with [ElasticLunr.js](http://elasticlunr.com/). [Read More](https://minicomp.github.io/wiki/#/wax/tasks/lunr?id=top).
+
+`$ bundle exec rake wax:lunr`
+
+```sh
+------------------------------------------------------------------------
+NOTE >> wax_lunr will also generate a default lunr UI to use if you run:
+        $ bundle exec rake wax:lunr UI=true
+------------------------------------------------------------------------
 ```
 
+### wax:iiif
+
+Takes a local directory of images and generates tiles and data that work with a IIIF compliant image viewer like [OpenSeaDragon](https://openseadragon.github.io/), [Mirador](http://projectmirador.org/), or [Leaflet IIIF](https://github.com/mejackreed/Leaflet-IIIF). [Read More](https://minicomp.github.io/wiki/#/wax/tasks/iiif?id=top).
+
+`$ bundle exec rake wax:iiif collection-name`
+
+### wax:test
+
+Runs [`htmlproofer`](https://github.com/gjtorikian/html-proofer) on your compiled site to look for broken links, HTML errors, and accessibility concerns. Runs [Rspec](http://rspec.info/) tests if a `.rspec` file is present. [Read More](https://minicomp.github.io/wiki/#/wax/tasks/test?id=top).
+
+`$ bundle exec rake wax:test`
+
 # Contributing
 
-Fork/clone the repository. After making code changes, run the tests (`$ bundle exec rubocop` and `$ bundle exec rspec`) before submitting a PR.
+Fork/clone the repository. After making code changes, run the tests (`$ bundle exec rubocop` and `$ bundle exec rspec`) before submitting a pull request. You can enable verbose tests with `$ DEBUG=true bundle exec rspec`.
+
+> __Note:__ The cannonical repository is [minicomp/wax_tasks](https://github.com/minicomp/wax_tasks/). Please submit all issues and pull requests to the [minicomp/wax_tasks](https://github.com/minicomp/wax_tasks/) repo.
+
+
+```sh
+---------------------------------------------------------------------------
+NOTE >> The cannonical repository is minicomp/wax_tasks. 
+        Please submit all issues and pull requests to the cannonical repo.
+---------------------------------------------------------------------------
+```
+<p align="right"><a href='https://github.com/minicomp/wax_tasks/'>minicomp/wax_tasks ~></a></p>
+
+# License
 
-> __Note:__ The cannonical repository is [minicomp/wax_tasks](https://github.com/minicomp/wax_tasks/). Please submit all issues and pull requests to the Minicomp repo.
+The gem is available as open source under the terms of the [MIT License](LICENSE).