feature: build groups

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

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