build groups: add convenience methods
This commit is contained in:
Andy Meneely
@@ -17,23 +17,24 @@ Only one group is enabled by default: ``:all``. All other groups are disabled by
|
||||
|
||||
Groups can be enabled and disabled in several ways:
|
||||
|
||||
* The :doc:`/dsl/enable_build` and :doc:`/dsl/disable_build` 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.
|
||||
* The :doc:`/dsl/enable_build` and :doc:`/dsl/disable_build` DSL methods within a given ``Squib::Deck`` 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. This is handy for enabling builds on the command line (e.g. turn on color, work in that for a while, then turn it off)
|
||||
* Furthermore, you can use :doc:`Squib.enable_build_globally </dsl/enable_build_globally>` and :doc:`Squib.disable_build_globally </dsl/disable_build_globally>` to manipulate ``SQUIB_BUILD`` environment variable programmatically (e.g. from a Rakefile, inside a `Guard <https://github.com/guard/guard>`_ session, or other build script).
|
||||
|
||||
Note that the environment variables are intended to change from run to run, from the command line.
|
||||
The :doc:`/guides/getting-started/part_3_workflows` tutorial covers how to work these features into your workflow.
|
||||
|
||||
.. note::
|
||||
|
||||
There should be no need to set the SQUIB_BUILD variable globally on your system.
|
||||
There should be no need to set the SQUIB_BUILD variable globally on your system (e.g. at boot). The intent is to set SQUIB_BUILD as part of your session.
|
||||
|
||||
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:
|
||||
One adaptation of this is to do the environment setting in a ``Rakefile``. `Rake <https://ruby.github.io/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:
|
||||
|
||||
|
||||
.. literalinclude:: ../samples/build_groups/Rakefile
|
||||
:language: ruby
|
||||
:linenos:
|
||||
|
||||
Thus, you can just run this code with commands like these::
|
||||
Thus, you can just run this code on the command line like these::
|
||||
|
||||
$ rake
|
||||
$ rake pnp
|
||||
|
||||
@@ -0,0 +1,46 @@
|
||||
disable_build_globally
|
||||
======================
|
||||
|
||||
Disable the given build group for all future ``Squib::Deck`` runs.
|
||||
|
||||
Essentially a convenience method for setting the ``SQUIB_BUILD`` environment variable. See :doc:`/build_groups` for ways to use this effectively.
|
||||
|
||||
This is a member of the ``Squib`` module, so you must run it like this::
|
||||
|
||||
Squib.disable_build_globally :pdf
|
||||
|
||||
The intended purpose of this method is to be able to alter the environment from other build scripts, such as a Rakefile.
|
||||
|
||||
Required Arguments
|
||||
------------------
|
||||
|
||||
build_group_name
|
||||
|
||||
the name of the build group to disable. Convention is to use a Ruby symbol.
|
||||
|
||||
|
||||
Examples
|
||||
--------
|
||||
|
||||
Can be used to disable a group, overriding setting the environment variable at the command line::
|
||||
|
||||
Squib.enable_build_globally :pdf
|
||||
Squib.disable_build_globally :pdf
|
||||
|
||||
Squib::Deck.new do
|
||||
build :pdf do
|
||||
save_pdf #does not get run regardless of incoming environment
|
||||
end
|
||||
end
|
||||
|
||||
But gets overridden by an individual ``Squib::Deck`` programmatically enabling a build via :doc:`/dsl/enable_build`::
|
||||
|
||||
Squib.enable_build_globally :pdf
|
||||
Squib.disable_build_globally :pdf
|
||||
|
||||
Squib::Deck.new do
|
||||
enable_build :pdf
|
||||
build :pdf do
|
||||
save_pdf # this will be run no matter what
|
||||
end
|
||||
end
|
||||
@@ -0,0 +1,44 @@
|
||||
disable_build_globally
|
||||
======================
|
||||
|
||||
Enagle the given build group for all future ``Squib::Deck`` runs.
|
||||
|
||||
Essentially a convenience method for setting the ``SQUIB_BUILD`` environment variable. See :doc:`/build_groups` for ways to use this effectively.
|
||||
|
||||
This is a member of the ``Squib`` module, so you must run it like this::
|
||||
|
||||
Squib.enable_build_globally :pdf
|
||||
|
||||
The intended purpose of this method is to be able to alter the environment from other build scripts, such as a Rakefile.
|
||||
|
||||
Required Arguments
|
||||
------------------
|
||||
|
||||
build_group_name
|
||||
|
||||
the name of the build group to enable. Convention is to use a Ruby symbol.
|
||||
|
||||
|
||||
Examples
|
||||
--------
|
||||
|
||||
Can be used to enable a group, overriding setting the environment variable at the command line::
|
||||
|
||||
Squib.enable_build_globally :pdf
|
||||
|
||||
Squib::Deck.new do
|
||||
build :pdf do
|
||||
save_pdf # this runs regardless of incoming environment
|
||||
end
|
||||
end
|
||||
|
||||
But gets overridden by an individual ``Squib::Deck`` programmatically enabling a build via :doc:`/dsl/enable_build`::
|
||||
|
||||
Squib.enable_build_globally :pdf
|
||||
|
||||
Squib::Deck.new do
|
||||
disable_build :pdf
|
||||
build :pdf do
|
||||
save_pdf # this will NOT be run no matter what
|
||||
end
|
||||
end
|
||||
@@ -35,19 +35,19 @@ Using Guard + Rake
|
||||
|
||||
Guard is a gem, just like Squib. When using Guard, I recommend also using Bundler. So your Gemfile will look like this.
|
||||
|
||||
.. literalinclude:: ../../samples/rake-guard/Gemfile
|
||||
.. literalinclude:: ../../samples/project/Gemfile
|
||||
:language: ruby
|
||||
:linenos:
|
||||
|
||||
And then your Rakefile might look something like this
|
||||
|
||||
.. literalinclude:: ../../samples/rake-guard/Rakefile
|
||||
.. literalinclude:: ../../samples/project/Rakefile
|
||||
:language: ruby
|
||||
:linenos:
|
||||
|
||||
To get our images directory set, and to turn on proress bars (which I recommend when working under Guard), you'll need a ``config.yml`` file that looks like this.
|
||||
|
||||
.. literalinclude:: ../../samples/rake-guard/config.yml
|
||||
.. literalinclude:: ../../samples/project/config.yml
|
||||
:language: yaml
|
||||
:linenos:
|
||||
|
||||
@@ -55,7 +55,7 @@ Note that we are using ``load`` instead of ``require`` to run our code. In Ruby,
|
||||
|
||||
And then our Guardfile
|
||||
|
||||
.. literalinclude:: ../../samples/rake-guard/Guardfile
|
||||
.. literalinclude:: ../../samples/project/Guardfile
|
||||
:language: ruby
|
||||
:linenos:
|
||||
|
||||
@@ -71,7 +71,7 @@ So, let's say we're working on our Character deck. To run all this we can kick o
|
||||
Loading SVG(s) <===========================================> 100% Time: 00:00:00
|
||||
Saving PNGs to _output/character__* <======================> 100% Time: 00:00:00
|
||||
]2;[running rake task: characters] watched files: []
|
||||
[1] Characters guard(main)> ow watching at 'C:/Users/andy/code/squib/samples/rake-guard'
|
||||
[1] Characters guard(main)> ow watching at 'C:/Users/andy/code/squib/samples/project'
|
||||
|
||||
Guard will do an initial build, then wait for file changes to be made. From here, once we edit and save anything related to characters - any Excel file, our ``characters.rb`` file, any YML file, etc, we'll rebuild our images.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user