bake 0.12.1 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5451e66cf2062b167b8b9983bb0308612b6234de8f99af360ddb1098e74d973e
-  data.tar.gz: feb9f86818d18175eab079b7875c3b3810d1017dcb82f717aaab2f02d04d44ed
+  metadata.gz: e4138c750ccdded2e0b36d082d94fecc0ae4afd0cfda6bad6e47179e37450f47
+  data.tar.gz: 236deaa42f0a148e195abdbeca1a8298e252ee335ea5cbceddc97e5c06dce195
 SHA512:
-  metadata.gz: 6043f4715eafdb780fea3c09ad50fe262d3e2a80234c4c76884b887bf0460e96f652bca576f5f5215d1d0aada420f33a0c8894fbc45ef2b10e716a075890e97c
-  data.tar.gz: dd58f182d931c1844d5b50794e55d0dd4ec5933fa201e2206adb6abf879b2aff19ab6030c0b2035186e748d5ef1070c34c518573d5fc3c4b7c8f679687ffe5af
+  metadata.gz: 0b249b795b9f91489d0150a5d511d3d22a6d4d2292fba3f2680455a2831c9b3480abed70d107127bf45cf76d5197395b9c9be597902800c39ca95be6e761ade8
+  data.tar.gz: ec9e06a913c3f457b227d077ae7d2e0f19d90ac7a417edcb3f1d721c0d6176dd62a178d5b6e2db5ff66084e60fda446af5c9f0ee013da98435fc15287e2f0726

data/README.md

@@ -2,7 +2,7 @@
 
 Bake is a task execution tool, inspired by Rake, but codifying many of the use cases which are typically implemented in an ad-hoc manner.
 
-[![Actions Status](https://github.com/ioquatix/bake/workflows/Development/badge.svg)](https://github.com/ioquatix/bake/actions?workflow=Development)
+[![Development](https://github.com/ioquatix/bake/workflows/Development/badge.svg)](https://github.com/ioquatix/bake/actions?workflow=Development)
 
 ## Motivation
 
@@ -23,81 +23,7 @@ Execute the following in your project:
 
 ## Usage
 
-Bake follows similar patterns to Rake.
-
-![Example](example.png)
-
-## Bakefile
-
-There is a root level `bake.rb` e.g.:
-
-```ruby
-def cake
-	ingredients = call 'supermarket:shop', 'flour,sugar,cocoa'
-	lookup('mixer:add').call(ingredients)
-end
-```
-
-This file is project specific and is the only file which can expose top level tasks (i.e. without a defined namespace). When used in a gem, these tasks are not exposed to other gems/projects.
-
-## Recipes
-
-Alongside the `bake.rb`, there is a `bake/` directory which contains files like `supermarket.rb`. These files contain recipes, e.g.:
-
-```ruby
-# @param ingredients [Array(Any)] the ingredients to purchase.
-def shop(ingredients)
-	supermarket = Supermarket.best
-	
-	return supermarket.purchase(ingredients)
-end
-```
-
-These methods are automatically scoped according to the file name, e.g. `bake/supermarket.rb` will define `supermarket:shop`.
-
-## Gems
-
-Adding a `bake/` directory to your gem will allow other gems and projects to consume those recipes. In order to prevent collisions, you *should* prefix your commands with the name of the gem, e.g. in `mygem/bake/mygem.rb`:
-
-```ruby
-def setup
-	# ...
-end
-```
-
-Then, in your project `myproject` which depends on `mygem`:
-
-```
-bake mygem:setup
-```
-
-## Arguments
-
-Arguments work as normal. Documented types are used to parse strings from the command line. Both positional and optional parameters are supported.
-
-### Positional Parameters
-
-```ruby
-# @param x [Integer]
-# @param y [Integer]
-def add(x, y)
-	puts x + y
-end
-```
-
-Which is invoked by `bake add 1 2`.
-
-### Optional Parameters
-
-```ruby
-# @param x [Integer]
-# @param y [Integer]
-def add(x:, y:)
-	puts x + y
-end
-```
-
-Which is invoked by `bake add x=1 y=2`.
+Please see the <a href="https://ioquatix.github.io/bake/">project documentation</a> or run it locally using `bake utopia:project:serve`.
 
 ## Contributing
 

data/bake.gemspec

@@ -14,7 +14,7 @@ Gem::Specification.new do |spec|
 	spec.metadata["donation_uri"] = "https://github.com/sponsors/ioquatix"
 	
 	spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
-		`git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+		`git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(docs|test|spec|features)/}) }
 	end
 	
 	spec.bindir = "bin"
@@ -25,6 +25,7 @@ Gem::Specification.new do |spec|
 	
 	spec.add_development_dependency 'bake-bundler'
 	
+	spec.add_development_dependency 'utopia-project'
 	spec.add_development_dependency 'covered'
 	spec.add_development_dependency 'bundler'
 	spec.add_development_dependency 'rspec'

data/gems.rb

@@ -2,4 +2,3 @@ source "https://rubygems.org"
 
 # Specify your gem's dependencies in bake.gemspec
 gemspec
-

data/guides/command-line-interface/README.md

@@ -0,0 +1,55 @@
+# Command Line Interface
+
+The `bake` command is broken up into two main functions: `list` and `call`.
+
+<pre>% bake --help
+<b>bake [-h/--help] [-b/--bakefile &lt;path&gt;] &lt;command&gt;</b>
+	<font color="#638FFF">Execute tasks using Ruby.</font>
+
+	[-h/--help]             Show help.                               
+	[-b/--bakefile &lt;path&gt;]  Override the path to the bakefile to use.
+	&lt;command&gt;               One of: call, list.                        (default: call)
+
+	<b>call &lt;commands...&gt;</b>
+		<font color="#638FFF">Execute one or more commands.</font>
+
+		&lt;commands...&gt;  The commands &amp; arguments to invoke.  (default: [&quot;default&quot;])
+
+	<b>list &lt;pattern&gt;</b>
+		&lt;pattern&gt;  The pattern to filter tasks by.
+</pre>
+
+## List
+
+The `bake list` command allows you to list all available recipes. By proving a pattern you will only see recipes that have a matching command name.
+
+<pre>$ bake list console
+<b>Bake::Loader console-1.8.2</b>
+
+	<b>console:info</b>
+		<font color="#638FFF">Increase the verbosity of the logger to info.</font>
+
+	<b>console:debug</b>
+		<font color="#638FFF">Increase the verbosity of the logger to debug.</font>
+</pre>
+
+The listing documents positional and optional arguments. The documentation is generated from the comments in the bakefiles.
+
+## Call
+
+The `bake call` (the default, so `call` can be omitted) allows you to execute one or more recipes. You must provide the name of the command, followed by any arguments.
+
+<pre>$ bake async:http:head https://www.codeotaku.com/index
+<font color="#638FFF"><b>                HEAD</b></font>: https://www.codeotaku.com/index
+<font color="#00AA00"><b>             version</b></font>: h2
+<font color="#00AA00"><b>              status</b></font>: 200
+<font color="#00AA00"><b>                body</b></font>: body with length <b>7879B</b>
+<b>        content-type</b>: &quot;text/html; charset=utf-8&quot;
+<b>       cache-control</b>: &quot;public, max-age=3600&quot;
+<b>             expires</b>: &quot;Mon, 04 May 2020 13:23:47 GMT&quot;
+<b>              server</b>: &quot;falcon/0.36.4&quot;
+<b>                date</b>: &quot;Mon, 04 May 2020 12:23:47 GMT&quot;
+<b>                vary</b>: &quot;accept-encoding&quot;
+</pre>
+
+You can specify multiple commands and they will be executed sequentially.

data/guides/gem-integration/README.md

@@ -0,0 +1,69 @@
+# Gem Integration
+
+This guide explains how to add `bake` to a Ruby gem and export standardised tasks for use by other gems and projects.
+
+## Exporting Tasks
+
+Adding a `bake/` directory to your gem will allow other gems and projects to consume those recipes. In order to prevent collisions, you *should* prefix your commands with the name of the gem, e.g. in `mygem/bake/mygem.rb`:
+
+~~~ ruby
+def setup
+	# ...
+end
+~~~
+
+Then, in a different project which depends on `mygem`, you can run tasks from `mygem` by invoking them using `bake`:
+
+~~~ bash
+$ bake mygem:setup
+~~~
+
+## Examples
+
+There are many gems which export tasks in this way. Here are some notable examples:
+
+### Variant
+
+The [variant gem](https://github.com/socketry/variant) exposes bake tasks for setting the environment e.g. `development`, `testing`, or `production`.
+
+<pre class="terminal">$ bake list variant
+<b>Bake::Loader variant-0.1.1</b>
+
+	<b>variant:production</b> <font color="#00AA00">**overrides</font>
+		<font color="#638FFF">Select the production variant.</font>
+		<font color="#00AA00">overrides</font> [Hash] <font color="#638FFF">any specific variant overrides.</font>
+
+	<b>variant:staging</b> <font color="#00AA00">**overrides</font>
+		<font color="#638FFF">Select the staging variant.</font>
+		<font color="#00AA00">overrides</font> [Hash] <font color="#638FFF">any specific variant overrides.</font>
+
+	<b>variant:development</b> <font color="#00AA00">**overrides</font>
+		<font color="#638FFF">Select the development variant.</font>
+		<font color="#00AA00">overrides</font> [Hash] <font color="#638FFF">any specific variant overrides.</font>
+
+	<b>variant:testing</b> <font color="#00AA00">**overrides</font>
+		<font color="#638FFF">Select the testing variant.</font>
+		<font color="#00AA00">overrides</font> [Hash] <font color="#638FFF">any specific variant overrides.</font>
+
+	<b>variant:force</b> <font color="#AA0000">name</font> <font color="#00AA00">**overrides</font>
+		<font color="#638FFF">Force a specific variant.</font>
+		<font color="#00AA00">name</font> [Symbol] <font color="#638FFF">the default variant.</font>
+		<font color="#00AA00">overrides</font> [Hash] <font color="#638FFF">any specific variant overrides.</font>
+
+	<b>variant:show</b>
+		<font color="#638FFF">Show variant-related environment variables.</font>
+</pre>
+
+### Console
+
+The [console gem](https://github.com/socketry/console) exposes bake tasks to change the log level.
+
+<pre class="terminal">$ bake list console
+<b>Bake::Loader console-1.8.2</b>
+
+	<b>console:info</b>
+		<font color="#638FFF">Increase the verbosity of the logger to info.</font>
+
+	<b>console:debug</b>
+		<font color="#638FFF">Increase the verbosity of the logger to debug.</font>
+</pre>

data/guides/project-integration/README.md

@@ -0,0 +1,64 @@
+# Project Integration
+
+This guide explains how to add `bake` to a Ruby project.
+
+## Bakefile
+
+At the top level of your project, you can create a `bake.rb` file, which contains top level tasks which are private to your project.
+
+~~~ ruby
+def cake
+	ingredients = call 'supermarket:shop', 'flour,sugar,cocoa'
+	lookup('mixer:add').call(ingredients)
+end
+~~~
+
+This file is project specific and is the only file which can expose top level tasks (i.e. without a defined namespace). When used in a gem, these tasks are not exposed to other gems/projects.
+
+## Recipes
+
+Alongside the `bake.rb`, there is a `bake/` directory which contains files like `supermarket.rb`. These files contain recipes, e.g.:
+
+~~~ ruby
+# @param ingredients [Array(Any)] the ingredients to purchase.
+def shop(ingredients)
+	supermarket = Supermarket.best
+	
+	return supermarket.purchase(ingredients)
+end
+~~~
+
+These methods are automatically scoped according to the file name, e.g. `bake/supermarket.rb` will define `supermarket:shop`.
+
+
+## Arguments
+
+Arguments work as normal. Documented types are used to parse strings from the command line. Both positional and optional parameters are supported.
+
+### Positional Parameters
+
+Positional parameters are non-keyword parameters which may have a default value. However, because of the limits of the command line, all positional arguments must be specified.
+
+~~~ ruby
+# @param x [Integer]
+# @param y [Integer]
+def add(x, y)
+	puts x + y
+end
+~~~
+
+Which is invoked by `bake add 1 2`.
+
+### Optional Parameters
+
+Optional parameters are keyword parameters which may have a default value. The parameter is set on the command line using the name of the parameter followed by an equals sign, followed by the value.
+
+~~~ ruby
+# @param x [Integer]
+# @param y [Integer]
+def add(x:, y: 2)
+	puts x + y
+end
+~~~
+
+Which is invoked by `bake add x=1`. Because `y` is not specified, it will default to `2` as per the method definition.

data/lib/bake/base.rb

@@ -22,7 +22,10 @@ require_relative 'recipe'
 require_relative 'scope'
 
 module Bake
+	# The base class for including {Scope} instances which define {Recipe} instances.
 	class Base < Struct.new(:context)
+		# Generate a base class for the specified path.
+		# @param path [Array(String)] The command path.
 		def self.derive(path = [])
 			klass = Class.new(self)
 			
@@ -31,6 +34,8 @@ module Bake
 			return klass
 		end
 		
+		# Format the class as a command.
+		# @return [String]
 		def self.to_s
 			if path = self.path
 				path.join(':')
@@ -47,20 +52,31 @@ module Bake
 			end
 		end
 		
+		# The path of this derived base class.
+		# @return [Array(String)]
 		def self.path
 			self.const_get(:PATH)
 		rescue
 			nil
 		end
 		
+		# The path for this derived base class.
+		# @return [Array(String)]
 		def path
 			self.class.path
 		end
 		
+		# Proxy a method call using command line arguments through to the {Context} instance.
+		# @param arguments [Array(String)]
 		def call(*arguments)
 			self.context.call(*arguments)
 		end
 		
+		# Recipes defined in this scope.
+		#
+		# @block `{|recipe| ...}`
+		# @yield recipe [Recipe]
+		# @return [Enumerable]
 		def recipes
 			return to_enum(:recipes) unless block_given?
 			
@@ -71,6 +87,9 @@ module Bake
 			end
 		end
 		
+		# Look up a recipe with a specific name.
+		#
+		# @param name [String] The instance method to look up.
 		def recipe_for(name)
 			Recipe.new(self, name)
 		end

data/lib/bake/command.rb

@@ -21,6 +21,7 @@
 require_relative 'command/top'
 
 module Bake
+	# The command line interface.
 	module Command
 		def self.call(*arguments)
 			Top.call(*arguments)

data/lib/bake/command/call.rb

@@ -26,6 +26,7 @@ require_relative '../context'
 
 module Bake
 	module Command
+		# Execute one or more commands.
 		class Call < Samovar::Command
 			self.description = "Execute one or more commands."
 			

data/lib/bake/command/list.rb

@@ -23,7 +23,10 @@ require 'set'
 
 module Bake
 	module Command
+		# List all available commands.
 		class List < Samovar::Command
+			self.description = "List all available commands."
+			
 			one :pattern, "The pattern to filter tasks by."
 			
 			def format_parameters(parameters, terminal)

data/lib/bake/command/top.rb

@@ -26,6 +26,7 @@ require_relative 'list'
 
 module Bake
 	module Command
+		# The top level command line application.
 		class Top < Samovar::Command
 			self.description = "Execute tasks using Ruby."
 			
@@ -56,12 +57,12 @@ module Bake
 				return terminal
 			end
 			
-			def bakefile
+			def bakefile_path
 				@options[:bakefile] || Dir.pwd
 			end
 			
 			def context
-				Context.load(self.bakefile)
+				Context.load(self.bakefile_path)
 			end
 			
 			def call

data/lib/bake/context.rb

@@ -21,11 +21,14 @@
 require_relative 'base'
 
 module Bake
+	# The default file name for the top level bakefile.
 	BAKEFILE = "bake.rb"
 	
+	# Represents a context of task execution, containing all relevant state.
 	class Context
+		# Search upwards from the specified path for a {BAKEFILE}.
 		# If path points to a file, assume it's a `bake.rb` file. Otherwise, recursively search up the directory tree starting from `path` to find the specified bakefile.
-		# @return [String, nil] the path to the bakefile if it could be found.
+		# @return [String | Nil] The path to the bakefile if it could be found.
 		def self.bakefile_path(path, bakefile: BAKEFILE)
 			if File.file?(path)
 				return path
@@ -52,6 +55,8 @@ module Bake
 			return nil
 		end
 		
+		# Load a context from the specified path.
+		# @path [String] A file-system path.
 		def self.load(path = Dir.pwd)
 			if bakefile_path = self.bakefile_path(path)
 				scope = Scope.load(bakefile_path)
@@ -68,6 +73,8 @@ module Bake
 			return self.new(loaders, scope, working_directory)
 		end
 		
+		# Initialize the context with the specified loaders.
+		# @param loaders [Loaders]
 		def initialize(loaders, scope = nil, root = nil)
 			@loaders = loaders
 			
@@ -92,10 +99,18 @@ module Bake
 			end
 		end
 		
+		# The loaders which will be used to resolve recipes in this context.
+		attr :loaders
+		
+		# The scope for the root {BAKEFILE}.
 		attr :scope
+		
+		# The root path of this context.
+		# @return [String | Nil]
 		attr :root
-		attr :loaders
 		
+		# Invoke recipes on the context using command line arguments.
+		# @param commands [Array(String)]
 		def call(*commands)
 			last_result = nil
 			
@@ -111,6 +126,8 @@ module Bake
 			return last_result
 		end
 		
+		# Lookup a recipe for the given command name.
+		# @param command [String] The command name, e.g. `bundler:release`.
 		def lookup(command)
 			@recipes[command]
 		end

data/lib/bake/documentation.rb

@@ -21,14 +21,21 @@
 require_relative 'scope'
 
 module Bake
+	# Structured access to a set of comment lines.
 	class Documentation
-		
+		# Initialize the documentation with an array of comments.
+		#
+		# @param comments [Array(String)] An array of comment lines.
 		def initialize(comments)
 			@comments = comments
 		end
 		
 		DESCRIPTION = /\A\s*([^@\s].*)?\z/
 		
+		# The text-only lines of the comment block.
+		#
+		# @yield [String]
+		# @return [Enumerable]
 		def description
 			return to_enum(:description) unless block_given?
 			
@@ -55,6 +62,11 @@ module Bake
 		
 		ATTRIBUTE = /\A\s*@(?<name>.*?)\s+(?<value>.*?)\z/
 		
+		# The attribute lines of the comment block.
+		# e.g. `@return [String]`.
+		#
+		# @yield [String]
+		# @return [Enumerable]
 		def attributes
 			return to_enum(:attributes) unless block_given?
 			
@@ -67,6 +79,11 @@ module Bake
 		
 		PARAMETER = /\A\s*@param\s+(?<name>.*?)\s+\[(?<type>.*?)\]\s+(?<details>.*?)\z/
 		
+		# The parameter lines of the comment block.
+		# e.g. `@param value [String] The value.`
+		#
+		# @yield [String]
+		# @return [Enumerable]
 		def parameters
 			return to_enum(:parameters) unless block_given?
 			

data/lib/bake/loader.rb

@@ -21,7 +21,10 @@
 require_relative 'scope'
 
 module Bake
+	# Represents a directory which contains bakefiles.
 	class Loader
+		# Initialize the loader with the specified root path.
+		# @param root [String] A file-system path.
 		def initialize(root, name: nil)
 			@root = root
 			@name = name
@@ -31,8 +34,12 @@ module Bake
 			"#{self.class} #{@name || @root}"
 		end
 		
+		# The root path for this loader.
 		attr :root
 		
+		# Enumerate all bakefiles within the loaders root directory.
+		# @block `{|path| ...}`
+		# @yield path [String] The Ruby source file path.
 		def each
 			return to_enum unless block_given?
 			
@@ -41,18 +48,8 @@ module Bake
 			end
 		end
 		
-		def recipe_for(path)
-			if book = lookup(path)
-				return book.lookup(path.last)
-			else
-				*path, name = *path
-				
-				if book = lookup(path)
-					return book.lookup(name)
-				end
-			end
-		end
-		
+		# Load the {Scope} for the specified relative path within this loader, if it exists.
+		# @param path [Array(String)] A relative path.
 		def scope_for(path)
 			*directory, file = *path
 			

data/lib/bake/loaders.rb

@@ -23,9 +23,12 @@ require 'console'
 require_relative 'loader'
 
 module Bake
+	# Structured access to the working directory and loaded gems for loading bakefiles.
 	class Loaders
 		include Enumerable
 		
+		# Create a loader using the specified working directory.
+		# @param working_directory [String]
 		def self.default(working_directory)
 			loaders = self.new
 			
@@ -34,15 +37,20 @@ module Bake
 			return loaders
 		end
 		
+		# Initialize an empty array of loaders.
 		def initialize
 			@roots = {}
 			@ordered = Array.new
 		end
 		
+		# Whether any loaders are defined.
+		# @return [Boolean]
 		def empty?
 			@ordered.empty?
 		end
 		
+		# Add loaders according to the current working directory and loaded gems.
+		# @param working_directory [String]
 		def append_defaults(working_directory)
 			# Load recipes from working directory:
 			self.append_path(working_directory)
@@ -51,32 +59,26 @@ module Bake
 			self.append_from_gems
 		end
 		
+		# Enumerate the loaders in order.
 		def each(&block)
-			return to_enum unless block_given?
-			
 			@ordered.each(&block)
 		end
 		
+		# Append a specific project path to the search path for recipes.
+		# The computed path will have `bake` appended to it.
+		# @param current [String] The path to add.
 		def append_path(current = Dir.pwd, **options)
-			recipes_path = File.join(current, "recipes")
 			bake_path = File.join(current, "bake")
 			
 			if File.directory?(bake_path)
 				return insert(bake_path, **options)
 			end
 			
-			if File.directory?(recipes_path)
-				Console.logger.warn(self) do |buffer|
-					buffer.puts "Recipes path: #{recipes_path.inspect} is deprecated."
-					buffer.puts "Please use #{bake_path.inspect} instead."
-				end
-				
-				return insert(recipes_path, **options)
-			end
-			
 			return false
 		end
 		
+		# Search from the current working directory until a suitable bakefile is found and add it.
+		# @param current [String] The path to start searching from.
 		def append_from_root(current = Dir.pwd, **options)
 			while current
 				append_path(current, **options)
@@ -91,6 +93,7 @@ module Bake
 			end
 		end
 		
+		# Enumerate all loaded gems and add them.
 		def append_from_gems
 			Gem.loaded_specs.each do |name, spec|
 				Console.logger.debug(self) {"Checking gem #{name}: #{spec.full_gem_path}..."}
@@ -101,12 +104,6 @@ module Bake
 			end
 		end
 		
-		def append_from_paths(paths, **options)
-			paths.each do |path|
-				append_path(path, **options)
-			end
-		end
-		
 		protected
 		
 		def insert(directory, **options)

data/lib/bake/recipe.rb

@@ -22,7 +22,13 @@ require_relative 'types'
 require_relative 'documentation'
 
 module Bake
+	# Structured access to an instance method in a bakefile.
 	class Recipe
+		# Initialize the recipe.
+		#
+		# @param instance [Base] The instance this recipe is attached to.
+		# @param name [String] The method name.
+		# @param method [Method | Nil] The method if already known.
 		def initialize(instance, name, method = nil)
 			@instance = instance
 			@name = name
@@ -35,21 +41,29 @@ module Bake
 			@arity = nil
 		end
 		
+		# The {Base} instance that this recipe is attached to.
 		attr :instance
+		
+		# The name of this recipe.
 		attr :name
 		
+		# Sort by location in source file.
 		def <=> other
 			self.source_location <=> other.source_location
 		end
 		
+		# The method implementation.
 		def method
 			@method ||= @instance.method(@name)
 		end
 		
+		# The source location of this recipe.
 		def source_location
 			self.method.source_location
 		end
 		
+		# The recipe's formal parameters, if any.
+		# @return [Array | Nil]
 		def parameters
 			parameters = method.parameters
 			
@@ -58,6 +72,8 @@ module Bake
 			end
 		end
 		
+		# Whether this recipe has optional arguments.
+		# @return [Boolean]
 		def options?
 			if parameters = self.parameters
 				type, name = parameters.last
@@ -66,6 +82,7 @@ module Bake
 			end
 		end
 		
+		# The command name for this recipe.
 		def command
 			@command ||= compute_command
 		end
@@ -74,6 +91,7 @@ module Bake
 			self.command
 		end
 		
+		# The method's arity, the required number of positional arguments.
 		def arity
 			if @arity.nil?
 				@arity = method.parameters.count{|type, name| type == :req}
@@ -82,6 +100,10 @@ module Bake
 			return @arity
 		end
 		
+		# Process command line arguments into the ordered and optional arguments.
+		# @param arguments [Array(String)] The command line arguments
+		# @return ordered [Array]
+		# @return options [Hash]
 		def prepare(arguments)
 			offset = 0
 			ordered = []
@@ -119,6 +141,7 @@ module Bake
 			return ordered, options
 		end
 		
+		# Call the recipe with the specified arguments and options.
 		def call(*arguments, **options)
 			if options?
 				@instance.send(@name, *arguments, **options)
@@ -128,22 +151,20 @@ module Bake
 			end
 		end
 		
-		def explain(context, *arguments, **options)
-			if options?
-				puts "#{self}(#{arguments.join(", ")}, #{options.inspect})"
-			else
-				puts "#{self}(#{arguments.join(", ")})"
-			end
-		end
-		
+		# Any comments associated with the source code which defined the method.
+		# @return [Array(String)] The comment lines.
 		def comments
 			@comments ||= read_comments
 		end
 		
+		# The documentation object which provides structured access to the {comments}.
+		# @return [Documentation]
 		def documentation
 			@documentation ||= Documentation.new(self.comments)
 		end
 		
+		# The documented type signature of the recipe.
+		# @return [Array] An array of {Types} instances.
 		def types
 			@types ||= read_types
 		end

data/lib/bake/scope.rb

@@ -21,7 +21,9 @@
 require_relative 'recipe'
 
 module Bake
+	# Used for containing all methods defined in a bakefile.
 	module Scope
+		# Load the specified file into a unique scope module, which can then be included into a {Base} instance.
 		def self.load(file_path, path = [])
 			scope = Module.new
 			scope.extend(self)
@@ -38,10 +40,11 @@ module Bake
 			"Bake::Scope<#{self.const_get(:FILE_PATH)}>"
 		end
 		
-		def recipe(name, **options, &block)
-			define_method(name, &block)
-		end
-		
+		# Recipes defined in this scope.
+		#
+		# @block `{|recipe| ...}`
+		# @yield recipe [Recipe]
+		# @return [Enumerable]
 		def recipes
 			return to_enum(:recipes) unless block_given?
 			
@@ -52,10 +55,14 @@ module Bake
 			end
 		end
 		
+		# The path of the file that was used to {load} this scope.
 		def path
 			self.const_get(:PATH)
 		end
 		
+		# Look up a recipe with a specific name.
+		#
+		# @param name [String] The instance method to look up.
 		def recipe_for(name)
 			Recipe.new(self, name, self.instance_method(name))
 		end

data/lib/bake/types/any.rb

@@ -20,43 +20,70 @@
 
 module Bake
 	module Types
-		module Type
-			def | other
-				Any.new([self, other])
-			end
-		end
-		
+		# An ordered list of types. The first type to match the input is used.
+		#
+		#	```ruby
+		#	type = Bake::Types::Any(Bake::Types::String, Bake::Types::Integer)
+		#	```
+		#
 		class Any
+			# Initialize the instance with an array of types.
+			# @param types [Array] the array of types.
 			def initialize(types)
 				@types = types
 			end
 			
+			# Create a copy of the current instance with the other type appended.
+			# @param other [Type] the type instance to append.
 			def | other
 				self.class.new([*@types, other])
 			end
 			
+			# Whether any of the listed types is a composite type.
+			# @return [Boolean] true if any of the listed types is `composite?`.
 			def composite?
 				@types.any?{|type| type.composite?}
 			end
 			
+			# Parse an input string, trying the listed types in order, returning the first one which doesn't raise an exception.
+			# @param input [String] the input to parse, e.g. `"5"`.
 			def parse(input)
 				@types.each do |type|
 					return type.parse(input)
 				rescue
-					# Ignore
+					# Ignore.
 				end
 			end
 			
+			# As a class type, accepts any value.
 			def self.parse(value)
 				value
 			end
 			
+			# Generate a readable string representation of the listed types.
 			def to_s
 				"any of #{@types.join(', ')}"
 			end
 		end
 		
-		def self.Any(types)
+		# An extension module which allows constructing `Any` types using the `|` operator.
+		module Type
+			# Create an instance of `Any` with the arguments as types.
+			# @param other [Type] the alternative type to match.
+			def | other
+				Any.new([self, other])
+			end
+		end
+		
+		# A type constructor.
+		#
+		#	```ruby
+		#	Any(Integer, String)
+		#	```
+		#
+		# See [Any.initialize](#Bake::Types::Any::initialize).
+		#
+		def self.Any(*types)
 			Any.new(types)
 		end
 	end

data/lib/bake/version.rb

@@ -19,5 +19,5 @@
 # THE SOFTWARE.
 
 module Bake
-	VERSION = "0.12.1"
+	VERSION = "0.13.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bake
 version: !ruby/object:Gem::Version
-  version: 0.12.1
+  version: 0.13.0
 platform: ruby
 authors:
 - Samuel Williams
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-04-30 00:00:00.000000000 Z
+date: 2020-05-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: samovar
@@ -38,6 +38,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: utopia-project
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: covered
   requirement: !ruby/object:Gem::Requirement
@@ -109,8 +123,10 @@ files:
 - bake.gemspec
 - bake.rb
 - bin/bake
-- example.png
 - gems.rb
+- guides/command-line-interface/README.md
+- guides/gem-integration/README.md
+- guides/project-integration/README.md
 - lib/bake.rb
 - lib/bake/base.rb
 - lib/bake/command.rb