runbook 0.12.1 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 15bd413c481c171d9ee7fca96b11c2b33c2d253c3f454e1b16daaf3e5d37fb31
-  data.tar.gz: b9400fe8bca1d7080e529093880331324bf8e353743a0242c959b9e945abb45d
+  metadata.gz: 5fe4b7ea15d7d74edf1a660fda55c9f8360a16f7e5032acadc427039240b9cf6
+  data.tar.gz: c72e2c91cd75587c87ed4b9e5921e1be050ea6466c59e1d903fefcf7f6770bfd
 SHA512:
-  metadata.gz: 967f09b95b45ad9e220c7ddea7b6136f646446ceaef9219fc89f14be0a147d300560d5fa4a6223f37f2b66b10e9af76ffb574262b56587abb7b16ad546424cdd
-  data.tar.gz: 6a204eda9e04545162d8c83ca23e6545c53df364aa5a6886aec0f0002dd920f27c0ccf4ca570e898faa9e6d1c72760ac48a915fb8cbda574e631b99184f67945
+  metadata.gz: 129f995881810339793273c74d00a872b62cd865f8712fe7db063356c95bdae7f090537d244383b00fbf81cf2de8555e59627248b9e4a6284320aa9594508ef1
+  data.tar.gz: b1c2ef5526b2225d02a246c2d4f5d8e657c599ab04faf96f192084ea4f11d61863f455abc91136a17174dd7645f1112231fa7614ed83862d4444debbc0d2ca07

data/CHANGELOG.md

@@ -4,6 +4,21 @@ This log maintains a list of all substantive changes to Runbook. The log include
 
 ## master
 
+## `v0.13.0` (2019-07-10)
+
+### Potentially Breaking Changes:
+
+* Uses of Runbook that expect the CLI to return a zero exit code may exhibit different behavior if their runbook encounters an error.
+
+### Fixes:
+
+* Return non-zero exit code on CLI error
+
+### New Features
+
+* Add runbook "generate" command, including generator, runbook, statement, dsl_extension, and project generators
+* Add "install" CLI command
+
 ## `v0.12.1` (2019-06-12)
 
 ### Fixes:

data/README.md

@@ -1,6 +1,6 @@
 # Runbook
 
-> Runbook is a framework for progressively automating system operations.
+[![Gem Version](https://badge.fury.io/rb/runbook.svg)](https://badge.fury.io/rb/runbook)
 
 Runbook provides a DSL for specifying a series of steps to execute an operation. Once your runbook is specified, you can use it to generate a formatted representation of the book or to execute the runbook interactively. For example, you can export your runbook to markdown or use the same runbook to execute commands on remote servers.
 
@@ -9,14 +9,14 @@ Runbook provides a DSL for specifying a series of steps to execute an operation.
 </div>
 <br>
 
-Runbook provides two modes for evaluating your runbook. The first mode, view mode, allows you to export your runbook into various formats such as markdown. The second mode, run mode, allows you to execute behavior based on the statements in your runbook.
+Runbook has two modes for evaluating your runbook. The first mode, view mode, allows you to export your runbook into various formats such as markdown. The second mode, run mode, allows you to execute behavior based on the statements in your runbook.
 
 <div align="center">
   <img width="600" src="images/runbook_execution_modes.png" alt="diagram of execution modes" />
 </div>
 <br>
 
-Runbook provides a very flexible interface. It can be integrated into your existing projects to add orchestration functionality, installed on systems as a stand-alone executable, or runbooks can be defined as self-executable scripts. In addition to being useful for automating common tasks, runbooks are a perfect bridge for providing operations teams with step-by-step instructions to handle common issues (especially when solutions cannot be easily automated).
+Runbook can be integrated into existing infrastructure in many different ways. It can be integrated into existing projects to add orchestration functionality, installed on systems as a stand-alone executable, or runbooks can be defined as self-executable scripts. In addition to being useful for automating common tasks, runbooks are a perfect bridge for providing operations teams with step-by-step instructions to handle common issues (especially when solutions cannot be easily automated).
 
 Lastly, Runbook provides an extendable interface for augmenting the DSL and defining your own behavior.
 
@@ -28,15 +28,18 @@ Lastly, Runbook provides an extendable interface for augmenting the DSL and defi
 * **Noop and Auto Modes** - Runbooks can be executed in noop mode. This allows you to see what a runbook will do before it executes. Runbooks can be run in auto mode to eliminate the need for human interaction.
 * **Execution Lifecycle Hooks** - Runbook provides before, after, around hooks to augment its execution behavior.
 * **Tmux Integration** - Runbook integrates with [tmux](https://github.com/tmux/tmux). You can define terminal pane layouts and send commands to terminal panes.
+* **Generators** - Runbook provides commands to generate runbooks, extensions, and runbook projects. You can define your own generators for easy, customized runbook creation.
 * **Extendable DSL** - Runbook's DSL is designed to be extendable. You can extend its DSL to add your own behavior.
 
 ## Use Cases
 
-Runbook is a very flexible tool. Though it can solve a myriad of problems, Runbook is best used for removing the need for repeated, rote developer operations. Runbook allows developers to execute processes at a higher level than that of individual command-line commands. Additionally, Runbook provides features to simply and safely execute operations in mission-critical environments.
+Though Runbook can solve a myriad of problems, it is best used for removing the need for repeated, rote developer operations. Runbook allows developers to execute processes at a higher level than that of individual command-line commands. Additionally, Runbook provides features to simply and safely execute operations in mission-critical environments.
 
 Runbook is not intended to replace more special-purpose automation solutions such as configuration management solutions (Puppet, Chef, Ansible, Salt), deployment solutions (Capistrano, Kubernetes, Docker Swarm), monitoring solutions (Nagios, Datadog), or local command execution (shell scripts, Rake tasks, Make). Instead Runbook is best used as a glue when needing to accomplish a task that cuts across these domains.
 
-## Installation
+## Quick Start
+
+### Installation
 
 Add this line to your application's Gemfile:
 
@@ -52,6 +55,62 @@ Or install it yourself as:
 
     $ gem install runbook
 
+### Your First Runbook
+
+Generate a runbook using the Runbook Generator:
+
+    $ runbook generate runbook my_first_runbook
+
+Execute the runbook:
+
+    $ runbook exec my_first_runbook.rb
+
+## Slightly Longer Start
+
+When setting up Runbook, you can install it at a system level, create a dedicated runbook project, or incorporate Runbook into an existing project.
+
+### System Level Setup
+
+Install runbook at a system level using `gem`:
+
+    $ gem install runbook
+
+Set any Runbook [configuration](#configuration) in `/etc/runbook.conf`.
+
+Generate runbook files using `runbook generate runbook`. Execute `runbook generate help runbook` for more details.
+
+Installing Runbook at a system level can be useful for executing runbooks on remote hosts or within docker containers. One disadvantage of installing Runbook at a system level is that there is no built-in solution for dependency management.
+
+### New Project Setup
+
+Install runbook using `gem`:
+
+    $ gem install runbook
+
+Generate a new runbook project:
+
+    $ runbook generate project <PROJECT_NAME>
+
+This will generate a new runbook project. Cd into your project directory and initialize its dependencies:
+
+    $ cd <PROJECT_NAME> && bin/setup
+
+### Existing Project Setup
+
+Add this line to your project's Gemfile:
+
+```ruby
+gem 'runbook'
+```
+
+Install the Runbook gem:
+
+    $ bundle install
+
+Install Runbook into your project:
+
+    $ bundle exec runbook install
+
 ## Contents
 
 * [1. Runbook Anatomy](#runbook-anatomy)
@@ -92,21 +151,24 @@ Or install it yourself as:
   * [4.5 Deep Nesting](#deep-nesting)
   * [4.6 Load Vs. Eval](#load-vs-eval)
   * [4.7 Passing State](#passing-state)
-* [5. Extending Runbook](#extending-runbook)
-  * [5.1 Adding Runs and Views](#adding-runs-and-views)
-  * [5.2 DSL Extensions](#dsl-extensions)
-  * [5.3 Adding New Statements](#adding-new-statements)
-  * [5.4 Adding Run and View Functionality](#adding-run-and-view-functionality)
-  * [5.5 Augmenting Functionality With Hooks](#augmenting-functionality-with-hooks)
-  * [5.6 Adding New Run Behaviors](#adding-new-run-behaviors)
-  * [5.7 Adding to Runbook's Run Metadata](#adding-to-runbooks-run-metadata)
-  * [5.8 Adding to Runbook's Configuration](#adding-to-runbooks-configuration)
-* [6. Known Issues](#known-issues)
-* [7. Development](#development)
-* [8. Contributing](#contributing)
-* [9. Feature Requests](#feature-requests)
-* [10. License](#license)
-* [11. Code of Conduct](#code-of-conduct)
+* [5. Generators](#generators)
+  * [5.1 Predefined Generators](#predefined-generators)
+  * [5.2 Custom Generators](#custom-generators)
+* [6. Extending Runbook](#extending-runbook)
+  * [6.1 Adding Runs and Views](#adding-runs-and-views)
+  * [6.2 DSL Extensions](#dsl-extensions)
+  * [6.3 Adding New Statements](#adding-new-statements)
+  * [6.4 Adding Run and View Functionality](#adding-run-and-view-functionality)
+  * [6.5 Augmenting Functionality With Hooks](#augmenting-functionality-with-hooks)
+  * [6.6 Adding New Run Behaviors](#adding-new-run-behaviors)
+  * [6.7 Adding to Runbook's Run Metadata](#adding-to-runbooks-run-metadata)
+  * [6.8 Adding to Runbook's Configuration](#adding-to-runbooks-configuration)
+* [7. Known Issues](#known-issues)
+* [8. Development](#development)
+* [9. Contributing](#contributing)
+* [10. Feature Requests](#feature-requests)
+* [11. License](#license)
+* [12. Code of Conduct](#code-of-conduct)
 
 ## Runbook Anatomy
 
@@ -496,7 +558,7 @@ If the `ssh_kit` configuration looks familiar, that's because it's an SSHKit Con
 
 ### Configuration Files
 
-Runbook automatically loads configuration from a number of predefined files. Runbook will attempt to load configuration from the following locations on startup: `/etc/runbook.conf`, a `Runbookfile` in a parent directory from the current directory, a `.runbook.conf` file in the current user's home directory, a file specified with `--config` on the command line, any configuration specified in a runbook. Runbook will also load configuration from these files in this order of preference, respectively. That is, configuration values specified at the project level (`Runbookfile`) will override configuration values set at the global level (`/etc/runbook.conf`), etc.
+Runbook loads configuration from a number of predefined files. Runbook will attempt to load configuration from the following locations on startup: `/etc/runbook.conf`, a `Runbookfile` in a parent directory from the current directory, a `.runbook.conf` file in the current user's home directory, a file specified with `--config` on the command line, any configuration specified in a runbook. Runbook will also load configuration from these files in this order of preference, respectively. That is, configuration values specified at the project level (`Runbookfile`) will override configuration values set at the global level (`/etc/runbook.conf`), etc.
 
 ## Working With Runbooks
 
@@ -617,7 +679,7 @@ The following are best practices when developing your own runbooks.
 
 ### Iterative Automation
 
-Runbooks allow for a very gradual transition from entirely manual operations to full automation. Runbooks can start out as a simple outline of all steps required to carry out an operation. From there, commands and prompts can be added to the runbook, actually carrying out and replacing the manual processes.
+Runbooks allow for a gradual transition from entirely manual operations to full automation. Runbooks can start out as a simple outline of all steps required to carry out an operation. From there, commands and prompts can be added to the runbook, actually carrying out and replacing the manual processes.
 
 Monitoring can transition from a process required by a human into something that can be codified and executed by your runbook. Eventually, the runner's `auto` flag can be used to allow the runbook to run uninterrupted without any human intervention. These runbooks can be triggered automatically in response to detected events. This will allow you to do more important things with your time, like eat ice cream.
 
@@ -739,6 +801,50 @@ Instance variables are only passed between statements such as `ruby_command`. Th
 
 Be careful with your naming of instance variables as it is possible to clobber the step's DSL methods because they share the same namespace.
 
+## Generators
+
+Runbook provides a number of generators accessible via the command line that can be used to generate code for new runbooks, Runbook projects, and Runbook extensions. Additionally, Runbook provides a generator generator so you can define your own custom generators.
+
+### Predefined Generators
+
+Runbook provides a number of predefined generators. You can see the full list using Runbook's command line help.
+
+    $ runbook help generate
+
+    Commands:
+      runbook generate dsl_extension NAME [options]  # Generate a dsl_extension for adding custom runbook DSL functionality
+      runbook generate generator NAME [options]      # Generate a runbook generator named NAME, e.x. acme_runbook
+      runbook generate help [COMMAND]                # Describe subcommands or one specific subcommand
+      runbook generate project NAME [options]        # Generate a project for your runbooks
+      runbook generate runbook NAME [options]        # Generate a runbook named NAME, e.x. deploy_nginx
+      runbook generate statement NAME [options]      # Generate a statement named NAME (e.x. ruby_command) that can be used in your runbooks
+
+    Base options:
+      -c, [--config=CONFIG]  # Path to runbook config file
+          [--root=ROOT]      # The root directory for your generated code
+                             # Default: .
+
+    Runtime options:
+      -f, [--force]                    # Overwrite files that already exist
+      -p, [--pretend], [--no-pretend]  # Run but do not make any changes
+      -q, [--quiet], [--no-quiet]      # Suppress status output
+      -s, [--skip], [--no-skip]        # Skip files that already exist
+
+Unless otherwise specified, all `NAME` arguments should be specified in a snake case format (e.x. `acme_runbook`). The `-p/--pretend` flag can be helpful for seeing what files a generator will create before it creates them.
+
+### Custom Generators
+
+The generator generator is useful for defining your own custom generators. Runbook uses [Thor Generators](https://github.com/erikhuda/thor/wiki/Generators) in the background, so any functionality you can do using Thor Generators can also be done using Runbook generators.
+
+Generate your own generator using the `generate generator` command
+
+    $ runbook generate generator my_new_generator --root lib/runbook/generators
+          create  my_new_generator
+          create  my_new_generator/templates
+          create  my_new_generator/my_new_generator.rb
+
+`my_new_generator/my_new_generator.rb` contains all the logic for generating your new code including arguments, options, and new files. ERB-templated files live in `my_new_generator/templates`. Remember to require your generator file in a runbook config file such as your `Runbookfile` so it can be loaded by the CLI. Generators cannot be required in config files specified at the command line due to the order with which the command line code is loaded. Once loaded, any child classes of `Runbook::Generators` will be included in Runbook's generator CLI.
+
 ## Extending Runbook
 
 Runbook can be extended to add custom functionality.
@@ -800,7 +906,7 @@ module Runbook::Statements
 end
 ```
 
-In the above example a keyword `diagram` will be automatically added to the step dsl and its arguments will be used to initialize the Diagram object.
+In the above example a keyword `diagram` will be added to the step dsl and its arguments will be used to initialize the Diagram object.
 
 ### Adding Run and View Functionality
 

data/TODO.md

@@ -1,10 +1,10 @@
 ## Desired feature list
 * [X] Revise README.md
-* [] capistrano-runbook gem that integrates runbook into capistrano tasks
-* [] Create a generator for a runbook? Allow for custom generators?
+* [X] Create a generator for a runbook? Allow for custom generators?
   * Generate runbook templates
   * Generate runbook projects with Runbookfile, Gemfile, etc.
   * Generate plugins
+* [] capistrano-runbook gem that integrates runbook into capistrano tasks
 * [] Add Appraisal to test against multiple versions of Ruby
 * [] Update output to be more log friendly, including timestamps for operations
 * [] Allow for preventing echo when prompting for input
@@ -15,11 +15,18 @@
 * [] Replace Thor with a solution that is more easily extendable (adding new flags, etc.)
 * [] Add goto statements for repeating steps (functionality exists in paranoid mode)
 * [] Add test statement
+* [] Add ruby_assert statement
 * [] Feedback on completion of tmux commands (when they complete, return values, outputs)
 * [] Add shorter aliases for tmux layout keys
 * [] Add host aliases for ssh_config setters
 * [] Allow for step dependencies that get executed before the step
 * [] Add periodic flush for sshkit output
+* [] Update assert attribute nomenclature (timeout_statement)
+* [] Update ssh_kit to count commands separately between steps
+* [] Create a plugin generator
+* [] Create generator for a new run (sshkit, etc.)
+* [] Create generator for a new view (markdown, yaml, html, etc.)
+* Add rake tasks to generators for viewing and executing runbooks
 * Add a way to execute a series of commands in groups
 * Docker testing story for more full-stack integration tests
   * Test integration with sshkit
@@ -34,5 +41,6 @@
   * Can convert from Ruby format to yaml (depending on compatibility) and yaml to Ruby
 * Guard for view updates (How to handle arguments?)
 * Be able to serve up markdown docs (web server) for easy viewing
+* Add interactive executable for all runbooks in a project
 * Could provide a rake task for compiling and nooping runbooks?
 * Can specify input-format, output-format, input (file), and output (file)

data/lib/runbook/cli.rb

@@ -1,17 +1,17 @@
 require "thor"
 require "runbook"
+require "runbook/cli_base"
+require "runbook/installer"
+
+# Needed to load custom generators
+Runbook::Configuration.load_config
+require "runbook/generator"
 
 module Runbook
   class CLI < Thor
-    map "--version" => :__print_version
-    class_option :config, aliases: :c, type: :string
+    include ::Runbook::CLIBase
 
-    def initialize(args = [], local_options = {}, config = {})
-      super(args, local_options, config)
-
-      cmd_name = config[:current_command].name
-      _set_cli_config(options[:config], cmd_name) if options[:config]
-    end
+    map "--version" => :__print_version
 
     desc "view RUNBOOK", "Prints a formatted version of the runbook"
     long_desc <<-LONGDESC
@@ -19,7 +19,7 @@ module Runbook
 
       With --view (-v), Prints the view using the specified view type
     LONGDESC
-    option :view, aliases: :v, type: :string, default: :markdown
+    option :view, aliases: "-v", type: :string, default: :markdown
     def view(runbook)
       runbook = _retrieve_runbook(runbook, :view)
       puts Runbook::Viewer.new(runbook).generate(
@@ -49,11 +49,11 @@ module Runbook
       With --start-at (-s),    Runs the runbook starting at the specified
                                section or step.
     LONGDESC
-    option :run, aliases: :r, type: :string, default: :ssh_kit
-    option :noop, aliases: :n, type: :boolean
-    option :auto, aliases: :a, type: :boolean
-    option :"no-paranoid", aliases: :P, type: :boolean
-    option :start_at, aliases: :s, type: :string, default: "0"
+    option :run, aliases: "-r", type: :string, default: :ssh_kit
+    option :noop, aliases: "-n", type: :boolean
+    option :auto, aliases: "-a", type: :boolean
+    option :"no-paranoid", aliases: "-P", type: :boolean
+    option :start_at, aliases: "-s", type: :string, default: "0"
     def exec(runbook)
       runbook = _retrieve_runbook(runbook, :exec)
       Runbook::Runner.new(runbook).run(
@@ -65,6 +65,23 @@ module Runbook
       )
     end
 
+    desc "generate GENERATOR", "Generate runbook objects from a template, such as runbooks, projects, or plugins."
+    long_desc <<-LONGDESC
+      Generates a runbook, runbook node, runbook project, or runbook plugin from a template.
+    LONGDESC
+    subcommand "generate", Runbook::Generator
+
+    desc "install", "Install Runbook into an existing project"
+    long_desc "Set up Runbook directory structure and Runbookfile in an existing project for executing runbooks."
+    Runbook::Installer.class_options.values.each do |co|
+      method_option co.name, desc: co.description, required: co.required,
+        default: co.default, aliases: co.aliases, type: co.type,
+        banner: co.banner, hide: co.hide
+    end
+    def install
+      invoke(Runbook::Installer)
+    end
+
     desc "--version", "Print runbook's version"
     def __print_version
       puts "Runbook v#{Runbook::VERSION}"
@@ -72,13 +89,6 @@ module Runbook
 
     private
 
-    def _set_cli_config(config, cmd)
-      unless File.exist?(config)
-        raise Thor::InvocationError, "#{cmd}: cannot access #{config}: No such file or directory"
-      end
-      Runbook::Configuration.cli_config_file = config
-    end
-
     def _retrieve_runbook(runbook, cmd)
       unless File.exist?(runbook)
         raise Thor::InvocationError, "#{cmd}: cannot access #{runbook}: No such file or directory"

data/lib/runbook/cli_base.rb

@@ -0,0 +1,38 @@
+module Runbook::CLIBase
+  def self.included(base)
+    base.extend(ClassMethods)
+
+    base.check_unknown_options!
+
+    base.class_option(
+      :config,
+      aliases: "-c",
+      type: :string,
+      group: :base,
+      desc: "Path to runbook config file"
+    )
+  end
+
+  def initialize(args = [], local_options = {}, config = {})
+    super(args, local_options, config)
+
+    cmd_name = config[:current_command].name
+    _set_cli_config(options[:config], cmd_name) if options[:config]
+  end
+
+  module ClassMethods
+    def exit_on_failure?
+      true
+    end
+  end
+
+  protected
+
+  def _set_cli_config(config, cmd)
+    unless File.exist?(config)
+      raise Thor::InvocationError, "#{cmd}: cannot access #{config}: No such file or directory"
+    end
+    Runbook::Configuration.cli_config_file = config
+    Runbook::Configuration.reconfigure
+  end
+end

data/lib/runbook/generator.rb

@@ -0,0 +1,38 @@
+module Runbook
+  class Generator < Thor
+    include Runbook::CLIBase
+    include Thor::Actions
+
+    Runbook::Generators::Base.set_base_options(self)
+
+    def self._unique_class_options(generator)
+      generator.class_options.values.reject do |class_option|
+        class_option.group == "Runtime" ||
+          class_option.group == "Base"
+      end
+    end
+
+    Runbook.generators.each do |generator|
+      desc(generator.usage, generator.description, generator.options)
+
+      long_desc(generator.long_description)
+
+      _unique_class_options(generator).each do |co|
+        method_option(
+          co.name,
+          desc: co.description,
+          required: co.required,
+          default: co.default,
+          aliases: co.aliases,
+          type: co.type,
+          banner: co.banner,
+          hide: co.hide,
+        )
+      end
+
+      define_method(generator.command) do |*args|
+        invoke(generator, args)
+      end
+    end
+  end
+end

data/lib/runbook/generators/base.rb

@@ -0,0 +1,45 @@
+module Runbook::Generators
+  module Base
+    def self.included(base)
+      base.extend(ClassMethods)
+      base.include(Thor::Actions)
+
+      set_base_options(base)
+      base.check_unknown_options!
+    end
+
+    def self.set_base_options(base)
+      base.class_option(
+        :root,
+        group: :base,
+        default: ".",
+        desc: "The root directory for your generated code",
+      )
+      base.add_runtime_options!
+    end
+
+    module ClassMethods
+      def command
+        self.to_s.gsub("Runbook::Generators::", "").underscore
+      end
+
+      def usage
+        args = arguments.map(&:banner).join(" ")
+        args += " " unless args.empty?
+        "#{command} #{args}[options]"
+      end
+
+      def description
+        "Generate a #{command}"
+      end
+
+      def long_description
+        description
+      end
+
+      def options
+        {}
+      end
+    end
+  end
+end

data/lib/runbook/generators/dsl_extension/dsl_extension.rb

@@ -0,0 +1,29 @@
+module Runbook::Generators
+  class DslExtension < Thor::Group
+    include ::Runbook::Generators::Base
+
+    source_root File.dirname(__FILE__)
+
+    def self.description
+      "Generate a dsl_extension for adding custom runbook DSL functionality"
+    end
+
+    def self.long_description
+      <<-LONG_DESC
+      This generator provides a template for extending Runbook's DSL. Using a
+      DSL extension, you can add custom commands to a book, section, or step
+      that can be used in your runbooks.
+      LONG_DESC
+    end
+
+    argument :name, desc: "The name of your dsl_extension, e.x. rollback_section"
+
+    def create_dsl_extension
+      target = File.join(
+        parent_options[:root],
+        "#{name.underscore}.rb",
+      )
+      template('templates/dsl_extension.tt', target)
+    end
+  end
+end

data/lib/runbook/generators/dsl_extension/templates/dsl_extension.tt

@@ -0,0 +1,25 @@
+# Remember to require this file in a runbook config file
+# or in your project so it is available in your runbooks
+# See https://github.com/braintree/runbook/tree/master/lib/runbook/extensions
+# for examples of DSL extensions
+module MyProject::RunbookExtensions
+  module <%= name.classify %>
+    module DSL
+      # def description(msg)
+      #   Runbook::Statements::Description.new(msg).tap do |desc|
+      #     # All DSLs can reference their parent object using
+      #     # the parent method. This allows you to modify the
+      #     # parent book, section, or step of the DSL
+      #     parent.add(desc)
+      #   end
+      # end
+    end
+  end
+
+  # Uncomment the below statements to add the the DSL methods to
+  # Book, Section, and Step DSLs respectively. Now this method can
+  # be called from the corresponding DSL in your runbooks
+  # Runbook::Entities::Book::DSL.prepend(<%= name.classify %>::DSL)
+  # Runbook::Entities::Section::DSL.prepend(<%= name.classify %>::DSL)
+  # Runbook::Entities::Step::DSL.prepend(<%= name.classify %>::DSL)
+end

data/lib/runbook/generators/generator/generator.rb

@@ -0,0 +1,43 @@
+module Runbook::Generators
+  class Generator < Thor::Group
+    include ::Runbook::Generators::Base
+
+    source_root File.dirname(__FILE__)
+
+    def self.usage
+      "generator NAME [options]"
+    end
+
+    def self.description
+      "Generate a runbook generator named NAME, e.x. acme_runbook"
+    end
+
+    argument :name, desc: "The name of your generator for populating boilerplate"
+
+    def create_generator_directory
+      target = File.join(
+        parent_options[:root],
+        name.underscore,
+      )
+      empty_directory(target)
+    end
+
+    def create_templates_directory
+      target = File.join(
+        parent_options[:root],
+        name.underscore,
+        "templates",
+      )
+      empty_directory(target)
+    end
+
+    def create_generator
+      target = File.join(
+        parent_options[:root],
+        name.underscore,
+        "#{name.underscore}.rb",
+      )
+      template('templates/generator.tt', target)
+    end
+  end
+end

data/lib/runbook/generators/generator/templates/generator.tt

@@ -0,0 +1,53 @@
+module Runbook::Generators
+  # Remember to require this class in a runbook config file such as your
+  # Runbookfile so it can be used from the command line. Note that you cannot
+  # require this generator from a config file specified on the command line.
+  class <%= name.classify %> < Thor::Group
+    include ::Runbook::Generators::Base
+
+    source_root File.dirname(__FILE__)
+
+    # Uncomment this method to customize the generator's usage
+    # description in runbook's help description.
+    #
+    # def self.usage
+    #   args = arguments.map(&:banner).join(" ")
+    #   args += " " unless args.empty?
+    #   "<%= name.underscore %> #{args}[options]"
+    # end
+
+    # Uncomment this method to customize the generator's
+    # description in runbook's help message.
+    #
+    # def self.description
+    #   "Generate a <%= name %>"
+    # end
+
+    # Uncomment this method to customize the generator's
+    # long description in runbook's help message.
+    #
+    # def self.long_description
+    #   <<-LONG_DESC
+    #   Here you can fully describe the options of your generator.
+    #   LONG_DESC
+    # end
+
+    # Argument example
+    # argument :name, desc: "The name of your <%= name.underscore %>, e.x. deploy_nginx"
+
+    # Option example
+    # class_option :include-readme, default: true, type: :boolean
+
+    # Example of a generator step
+    # See: https://github.com/erikhuda/thor/wiki/Generators
+    # for further documentation on using thor generators.
+    #
+    # def create_<%= name.underscore %>
+    #   target = File.join(
+    #     parent_options[:root],
+    #     "#{name.underscore}.rb",
+    #   )
+    #   template('templates/<%= name.underscore %>.tt', target)
+    # end
+  end
+end