feature: build groups

See docs and changelog for more details on how these work.

.gitmodules

@@ -12,3 +12,6 @@
 [submodule "samples/autoscale_font"]
 	path = samples/autoscale_font
 	url = https://gist.github.com/andymeneely/a4536fff0f3dc5d59c66
+[submodule "samples/build_groups"]
+	path = samples/build_groups
+	url = git@gist.github.com:bda48487e3b8c9d15edb.git

CHANGELOG.md

@@ -3,8 +3,12 @@ Squib follows [semantic versioning](http://semver.org).
 
 ## v0.10.0 / Unreleased
 
+Features:
+* Build groups! Simplify the process of building your deck different ways (e.g. one for color, one for PNP). Can be enabled explicitly or via command line. [See our shiny new docs for how these work](http://squib.readthedocs.org).
+
 Chores:
 * Switched to `require_relative` internally throughout the codebase to be more pry-friendly (#130)
+* Rewrote the entire API doc and placed it on [squib.readthedocs.org](http://squib.readthedocs.org)
 
 ## v0.9.0 / 2016-01-10
 

docs/build_groups.rst

@@ -0,0 +1,47 @@
+Use Groups for Custom Builds
+============================
+
+Often in the prototyping process you'll find yourself cycling between running your overall build and building a single card. You'll probably be commenting out code in the process.
+
+And even after your code is stable, you'll probably want to build your deck multiple ways: maybe a printer-friendly black-and-white version for print-and-play and then a full color version.
+
+Squib's Build Groups help you with these situations. By grouping your Squib code into different groups, you can run parts of it at a time without having to go back and commenting out code.
+
+Here's a basic example:
+
+.. raw:: html
+
+  <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
+  <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/gist-embed/2.4/gist-embed.min.js"></script>
+  <code data-gist-id="bda48487e3b8c9d15edb" data-gist-file="build_groups.rb"></code>
+
+Only one group is enabled by default: ``:all``. All other groups are disabled by default. To see which groups are enabled currently, the :doc:`/dsl/groups` returns the set.
+
+Groups can be enabled and disabled in several ways:
+
+  * The :doc:`/dsl/enable_group` and :doc:`/dsl/disable_group`  DSL methods can explicitly enable/disable a group. Again, you're back to commenting out the *enable_group* call, but that's easier than remembering what lines to comment out each time.
+  * When a ``Squib::Deck`` is initialized, the `environment variable <https://en.wikipedia.org/wiki/Environment_variable>`_ ``SQUIB_BUILD`` is consulted for a comma-separated string. These are converted to Ruby symbols and the corresponding groups are enabled.
+
+Note that the environment variables are intended to change from run to run, from the command line (see above gist for examples in various OS's).
+
+.. note::
+
+  There should be no need to set the SQUIB_BUILD variable globally on your system.
+
+Don't like how Windows specifies environment variables? One adaptation of this is to do the environment setting in a ``Rakefile``. Rake is the build utility that comes with Ruby, and it allows us to set different tasks exactly in this way. This Rakefile works nicely with our above code example:
+
+
+.. raw:: html
+
+  <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
+  <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/gist-embed/2.4/gist-embed.min.js"></script>
+  <code data-gist-id="bda48487e3b8c9d15edb" data-gist-file="Rakefile"></code>
+
+
+Thus, you can just run this code with commands like these::
+
+  $ rake
+  $ rake pnp
+  $ rake color
+  $ rake test
+  $ rake both

docs/dsl/disable_group.rst

@@ -0,0 +1,16 @@
+disable_group
+=============
+
+Disable the given build group for the rest of the build. Thus, code within the corresponding :doc:`/dsl/group` block will not be executed. See :doc:`/build_groups` for ways to use this effectively.
+
+
+Required Arguments
+------------------
+
+group
+  the name of the group to disable. Convention is to use a Ruby symbol.
+
+
+
+Examples
+--------

docs/dsl/enable_group.rst

@@ -0,0 +1,16 @@
+enable_group
+=============
+
+Enable the given build group for the rest of the build. Thus, code within the corresponding :doc:`/dsl/group` block will be executed. See :doc:`/build_groups` for ways to use this effectively.
+
+
+Required Arguments
+------------------
+
+group
+  the name of the group to enable. Convention is to use a Ruby symbol.
+
+
+
+Examples
+--------

docs/dsl/group.rst

@@ -0,0 +1,28 @@
+group
+=====
+
+Establish a set of commands that can be enabled/disabled together to allow for customized builds. See :doc:`/build_groups` for ways to use this effectively.
+
+Required Arguments
+------------------
+
+group
+  default: ``:all``
+
+  The name of the group. Convention is to use a Ruby symbol.
+
+
+&block
+  When this group is enabled (and only ``:all`` is enabled by default), then this block is executed. Otherwise, the block is ignored.
+
+
+Examples
+--------
+
+Use group to organize your Squib code into build groups::
+
+  Squib::Deck.new do
+    group :pnp do
+      save_pdf
+    end
+  end

docs/dsl/groups.rst

@@ -0,0 +1,23 @@
+groups
+======
+
+Returns the set of group names that have been enabled. See :doc:`/build_groups` for ways to use this effectively.
+
+Arguments
+---------
+
+(none)
+
+
+Examples
+--------
+
+Use group to organize your Squib code into build groups::
+
+  Squib::Deck.new do
+    enable_group :pnp
+    group :pnp do
+      save_pdf
+    end
+    puts groups # outputs :all and :pnp
+  end

docs/index.rst

@@ -20,6 +20,7 @@ Contents:
    bleed
    config
    backends
+   build_groups
    help
    dsl/index.rst
 

docs/server.bat

@@ -0,0 +1 @@
+sphinx-autobuild . _build/html

lib/squib/api/groups.rb

@@ -0,0 +1,47 @@
+require 'set'
+
+module Squib
+
+  # An idea for later...
+  # def enable_group_env group
+  #   ENV['SQUIB_BUILD'] ||= ''
+  #   ENV['SQUIB_BUILD'] += ','
+  #   ENV['SQUIB_BUILD'] += group
+  # end
+  # module_function :enable_group_env
+
+  class Deck
+
+    # See official API docs
+    def group grp = :all, &block
+      raise 'Please provide a block' unless block_given?
+      block.yield if groups.include? grp
+    end
+
+    # See official API docs
+    def enable_group grp
+      groups # make sure it's initialized
+      @build_groups << grp
+    end
+
+    # See official API docs
+    def disable_group grp
+      groups # make sure it's initialized
+      @build_groups.delete grp
+    end
+
+    # See official API docs
+    def groups
+      @build_groups ||= Set.new.add(:all)
+    end
+
+    # See official API docs
+    def enable_groups_from_env!
+      return if ENV['SQUIB_BUILD'].nil?
+      ENV['SQUIB_BUILD'].split(',').each do |grp|
+        enable_group grp.strip.to_sym
+      end
+    end
+
+  end
+end

lib/squib/deck.rb

@@ -69,6 +69,7 @@ module Squib
       @height        = Args::UnitConversion.parse height, dpi
       cards.times{ |i| @cards << Squib::Card.new(self, @width, @height, i) }
       @layout        = LayoutParser.load_layout(layout)
+      enable_groups_from_env!
       if block_given?
         instance_eval(&block) # here we go. wheeeee!
       end
@@ -102,6 +103,7 @@ module Squib
     ##################
     require_relative 'api/background'
     require_relative 'api/data'
+    require_relative 'api/groups'
     require_relative 'api/image'
     require_relative 'api/save'
     require_relative 'api/settings'

samples/build_groups

@@ -0,0 +1 @@
+Subproject commit 064cd9e28d522e9253df8f946755d9d2556ef56b