plans 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: f36f44001dbc8ddb84a61c9095b71c3e24fc69a7
+  data.tar.gz: 7ebd2e8cd146d988773051f9cfd45a8b23c756e6
+SHA512:
+  metadata.gz: 8c2c886d74043230a8b91e53ad529b1d47123b5f1fdf7b98540e90282d7b3a14cbc69ecb58860bdb23766760bb72752ab5b8e3312c752c57806efbf760fc39c7
+  data.tar.gz: 76c9b7a979b23e11b020a3df2619a8ea152c044c862860fc11beb3150426f0245ed4edfec0341eedcb4da84cb63ed90c4b1100661aeced923ea20d1b71deccc2

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--require spec_helper
+--format documentation

data/.versions.conf

@@ -0,0 +1,2 @@
+ruby=ruby-2.2.3
+ruby-gemset=plans

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in plans.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,102 @@
+PATH
+  remote: .
+  specs:
+    plans (0.1.0)
+      thor
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    aruba (0.13.0)
+      childprocess (~> 0.5.6)
+      contracts (~> 0.9)
+      cucumber (>= 1.3.19)
+      ffi (~> 1.9.10)
+      rspec-expectations (>= 2.99)
+      thor (~> 0.19)
+    builder (3.2.2)
+    childprocess (0.5.9)
+      ffi (~> 1.0, >= 1.0.11)
+    coderay (1.1.1)
+    contracts (0.13.0)
+    cucumber (2.3.2)
+      builder (>= 2.1.2)
+      cucumber-core (~> 1.4.0)
+      cucumber-wire (~> 0.0.1)
+      diff-lcs (>= 1.1.3)
+      gherkin (~> 3.2.0)
+      multi_json (>= 1.7.5, < 2.0)
+      multi_test (>= 0.1.2)
+    cucumber-core (1.4.0)
+      gherkin (~> 3.2.0)
+    cucumber-wire (0.0.1)
+    diff-lcs (1.2.5)
+    ffi (1.9.10)
+    formatador (0.2.5)
+    gherkin (3.2.0)
+    guard (2.13.0)
+      formatador (>= 0.2.4)
+      listen (>= 2.7, <= 4.0)
+      lumberjack (~> 1.0)
+      nenv (~> 0.1)
+      notiffany (~> 0.0)
+      pry (>= 0.9.12)
+      shellany (~> 0.0)
+      thor (>= 0.18.1)
+    guard-compat (1.2.1)
+    guard-rspec (4.6.4)
+      guard (~> 2.1)
+      guard-compat (~> 1.1)
+      rspec (>= 2.99.0, < 4.0)
+    listen (3.0.6)
+      rb-fsevent (>= 0.9.3)
+      rb-inotify (>= 0.9.7)
+    lumberjack (1.0.10)
+    method_source (0.8.2)
+    multi_json (1.11.2)
+    multi_test (0.1.2)
+    nenv (0.3.0)
+    notiffany (0.0.8)
+      nenv (~> 0.1)
+      shellany (~> 0.0)
+    pry (0.10.3)
+      coderay (~> 1.1.0)
+      method_source (~> 0.8.1)
+      slop (~> 3.4)
+    rake (10.5.0)
+    rb-fsevent (0.9.7)
+    rb-inotify (0.9.7)
+      ffi (>= 0.5.0)
+    rspec (3.4.0)
+      rspec-core (~> 3.4.0)
+      rspec-expectations (~> 3.4.0)
+      rspec-mocks (~> 3.4.0)
+    rspec-core (3.4.3)
+      rspec-support (~> 3.4.0)
+    rspec-expectations (3.4.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.4.0)
+    rspec-mocks (3.4.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.4.0)
+    rspec-support (3.4.1)
+    shellany (0.0.1)
+    slop (3.6.0)
+    terminal-notifier-guard (1.7.0)
+    thor (0.19.1)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  aruba
+  bundler (~> 1.10)
+  guard
+  guard-rspec
+  plans!
+  rake (~> 10.0)
+  rspec
+  terminal-notifier-guard
+
+BUNDLED WITH
+   1.11.2

data/Guardfile

@@ -0,0 +1,46 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+## Uncomment and set this to only include directories you want to watch
+# directories %w(app lib config test spec features) \
+#  .select{|d| Dir.exists?(d) ? d : UI.warning("Directory #{d} does not exist")}
+
+## Note: if you are using the `directories` clause above and you are not
+## watching the project directory ('.'), then you will want to move
+## the Guardfile to a watched dir and symlink it back, e.g.
+#
+#  $ mkdir config
+#  $ mv Guardfile config/
+#  $ ln -s config/Guardfile .
+#
+# and, you'll have to watch "config/Guardfile" instead of "Guardfile"
+
+# Note: The cmd option is now required due to the increasing number of ways
+#       rspec may be run, below are examples of the most common uses.
+#  * bundler: 'bundle exec rspec'
+#  * bundler binstubs: 'bin/rspec'
+#  * spring: 'bin/rspec' (This will use spring if running and you have
+#                          installed the spring binstubs per the docs)
+#  * zeus: 'zeus rspec' (requires the server to be started separately)
+#  * 'just' rspec: 'rspec'
+
+guard :rspec, cmd: "bin/rspec" do
+  require "guard/rspec/dsl"
+  dsl = Guard::RSpec::Dsl.new(self)
+
+  # Feel free to open issues for suggestions and improvements
+
+  # RSpec files
+  rspec = dsl.rspec
+  watch(rspec.spec_helper) { rspec.spec_dir }
+  watch(rspec.spec_support) { rspec.spec_dir }
+  watch(rspec.spec_files)
+
+  # Ruby files
+  ruby = dsl.ruby
+  dsl.watch_spec_files_for(ruby.lib_files)
+
+  # Lib files
+  watch(%r{^lib/plans/(.+)\.rb$}) { |m| "spec/#{m[1]}_spec.rb" }
+
+end

data/LICENSE

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Aramis Group, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

data/README.md

@@ -0,0 +1,100 @@
+# Plans
+
+Command line application for creating markdown documents from templates and publishing them in MS Word.
+
+> Plans are nothing; planning is everything. --Dwight D. Eisenhower
+
+Plans was originally created to manage functional specifications and scope documents for our projects. I prefer to write in [markdown](https://daringfireball.net/projects/markdown/), but many of our clients would prefer to review documents in MS Word. Plans (well [Pandoc](http://pandoc.org) really!) bridges that gap allowing us to create these documents in markdown and publish them in MS Word. It also allows us to manage our requirements documents more like code. We keep them all in git (either on [Github](https://github.com) or [Bitbucket](https://bitbucket.org)) and manage changes to them via pull requests. As a side benefit, the built in markdown browsing capabilities available on both BitBucket and GitHub are really handy. That's why, as you will see, most of the markdown files in the documents are named README.md. This way they are available in GitHub or BitBucket as the Readme file for the directory.
+
+Plans ships with templates (DOC_TYPEs) for managing the requirements for a typical project.
+
+* Vision and Scope document
+* Functional Specification
+* User Classes and Characteristics
+* Glossary
+* Plain Document 
+
+These are just examples and its easy to make your own templates. We also use plans to manage our proposals, agreements, and statements of work.
+
+## Prerequisites
+
+Plans has only been tested on MacOS. If you *really* want to use it in Windows, let me know.
+
+Plans depends on [Pandoc](http://pandoc.org) and [ImageMagik](http://imagemagick.org) to do a lot of the heavy lifting. These will need to be installed first.
+
+There are many ways to do this, but probably the easiest is to use [Homebrew](http://brew.sh).
+
+Once homebrew is installed, you can easily install Pandoc.
+
+    $ brew install pandoc
+    
+ImageMagick works pretty much the same way.
+
+    $ brew install imagemagick
+
+You also need Microsoft Word. :)
+
+## Installation
+
+Install it:
+
+    $ gem install plans
+
+## Usage
+
+To get started, try:
+
+    $ plans help
+    
+This will show you what plans can do. It will also let you know if you have plans installed correctly.
+
+Plans allows you to define a set of document templates, or DOC_TYPEs. These are stored in your home directory in a `.plans` folder. To create this folder with a default set of documents do the following.
+
+    $ plans init
+
+Then take a look at the `.plans` directory in your home directory. If you want to customize the templates, check out the README.md in the root of the `.plans` directory.
+
+To see what types of documents you can create do the following.
+
+    $ plans list
+
+To create a new functional specification, do the following.
+
+    $ plans new functional
+
+You can then edit the README.md that is created by plans. To turn that markdown document into MS Word, just navigate into the directory where the file is located and type:
+
+    $ plans publish
+
+### Images
+
+Making an image heavy document in markdown can be kind of a pain and functional specifications for a user interface tend to have a lot of mockups, screenshots, and diagrams. With plans, you can just export those images to the `img` folder and include them like you would for markdown normally. Something like this:
+
+    ![A Screenshot](./img/Fullscreen_10_12_15__11_34_AM.png)
+
+This is all well and good, but sometimes those images are huge and they don't get automatically resized in Word. Manually resizing all of the images in a Word document rapidly becomes very tedious.
+
+So, plans uses Imagemagick to make reasonable sized versions of any images in your documents `img` folder. To learn more, try:
+
+    $ plans help thumbs
+
+Plans will make 200px, 400px, and 600px wide versions of these images. You can then include them in your document like this:
+
+    ![A Screenshot](./img/400px/Fullscreen_10_12_15__11_34_AM.png)
+
+No more manually resizing images in Word!
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/code-lever/plans.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
+

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/_guard-core

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application '_guard-core' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('guard', '_guard-core')

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "plans"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/guard

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application 'guard' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('guard', 'guard')

data/bin/rake

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application 'rake' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('rake', 'rake')

data/bin/rspec

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+# This file was generated by Bundler.
+#
+# The application 'rspec' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require 'pathname'
+ENV['BUNDLE_GEMFILE'] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+require 'rubygems'
+require 'bundler/setup'
+
+load Gem.bin_path('rspec-core', 'rspec')

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/exe/plans

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require "plans"
+
+Plans::CLI.start(ARGV)

data/lib/plans/cli.rb

@@ -0,0 +1,121 @@
+require 'thor'
+require 'plans/new'
+require 'plans/list'
+require 'plans/init'
+require 'plans/publish'
+require 'plans/thumbs'
+
+module Plans
+  class CLI < Thor
+    include Thor::Actions
+
+    # Set the source root for Thor::Actions
+    def self.source_root
+      Plans.source_root
+    end
+
+    # Override for Thor.
+    # Have the application exit and return an error code on failure.
+    def self.exit_on_failure?
+      true
+    end
+
+    class_option :'plans-path',
+                 {:type => :string,
+                  :desc => 'The path to the .plans directory which contains the plans templates. This is your home directory by default.'}
+
+
+    desc 'new DOC_TYPE', 'Creates a new document of the specified type in the current directory.'
+    long_desc <<-NEW
+    `plans new DOC_TYPE` creates a new document of the specified type.
+
+    To see the available document types try `plans list`.
+
+    > $ plans new scope
+    NEW
+
+    def new(doc_type)
+      New.new(shell, options).do(doc_type)
+    end
+
+    desc 'list', 'List all of the document types available.'
+    long_desc <<-LIST
+    `plans list` Lists all the documents types available.
+
+    > $ plans list
+    LIST
+
+    def list
+      List.new(shell, options).do
+    end
+
+
+    desc 'init', 'Create the .plans folder in your home directory and initialize it with the default document templates'
+    long_desc <<-INIT
+    `plans init` Creates the .plans folder in your home directory and initializes it with the default document templates.
+    Once you have the templates customized the way you like them, its probably a good idea to put this directory
+    into version control.
+
+    If the directory already exists, the command does nothing.
+
+    > $ plans init
+    INIT
+
+    def init
+      Init.new(shell, options).do
+    end
+
+    desc 'publish', 'Create an MS Word version of the document'
+    long_desc <<-PUBLISH
+    `plans publish` will create a MS Word version of the document.
+
+    The document type is determined by inspecting the template.yml.
+
+    Overwrites any previously published versions of the Word document.
+
+    > $ plans publish
+    PUBLISH
+    method_option :toc,
+                  {:type => :boolean,
+                   :default => false,
+                   :desc => 'Add a table of contents to the MS Word document. Not included by default.'}
+    method_option :open,
+                  {:type => :boolean,
+                   :default => true,
+                   :desc => 'Open the published document after it has been rendered by Pandoc.'}
+
+    def publish(path = '.')
+      Publish.new(shell, options).do(path)
+    end
+
+    desc 'thumbs', 'Creates reduced size copies of each of the images in the img directory'
+    long_desc <<-THUMBS
+        `plans thumbs` will create reduced size versions of
+        each of the images in the document's img directory. Markdown isn't
+        very good at scaling images, so images of a known width are useful.
+        Images like desktop screenshots are often too large to fit on the
+        printed or published page without being manually scaled.
+
+        The command creates three subdirectories in the
+        documents img directory, one for each size of scaled image. These
+        are 200px, 400px, and 600px. To use these in the document, just
+        use the standard markdown syntax for including an image. The following
+        shows how to include a 400px wide version of a screenshot
+
+        `![A Screenshot](./img/400px/Fullscreen_10_12_15__11_34_AM.png)`
+
+        The thumbnail directories are removed each time the thumbnails are
+        generated, so do not place additional files in these directories.
+
+        > $ plans thumbs
+    THUMBS
+
+    def thumbs(path = '.')
+      Thumbs.new(shell, options).do(path)
+    end
+
+  end
+end
+
+
+

data/lib/plans/command.rb

@@ -0,0 +1,61 @@
+require 'thor'
+
+module Plans
+  class Command
+    # To get your hands on the `from_superclass` method
+    include Thor::Base
+
+    # Allow us to use nice Thor helper methods like 'directory'
+    include Thor::Actions
+
+    # Set the source root for Thor::Actions
+    def self.source_root
+      Plans.source_root
+    end
+
+    attr_reader :shell, :options
+
+    # Initialize the command with the
+    # Thor::Shell and the options.
+    def initialize(shell, options)
+      @shell = shell
+      @options = options
+    end
+
+    # Check to see if the .plans path exists
+    # Prints a message for the user and raises if it does not.
+    #
+    # @param [Pathname] path the proposed path to the .plans directory.
+    def check_plans_pathname_exists(path)
+      unless path.exist?
+        say 'The .plans directory does not exist.', :red
+        say 'Run `plans init` to create a .plans folder in your home directory and initialize it with the default document templates.'
+        say "  #{@path}"
+        raise_error('Plans directory does not exist.')
+      end
+    end
+
+    # The full current path, as a pathname object.
+    # @return [Pathname] The full path to the directory where the command is to be executed.
+    def pathname(path)
+      Pathname(File.expand_path(path))
+    end
+
+    # Get the path as a pathname object to the
+    # .plans directory.
+    #
+    # @param [String] path The string path to the .plans directory
+    #   or nil if the users home directory should be used.
+    def plans_pathname(path = nil)
+      path = path || Dir.home
+      pathname(path) + '.plans'
+    end
+
+    # Raise a formatted Thor exception.
+    #
+    # @param [String] msg the message to include in the exception.
+    def raise_error(msg)
+      raise Thor::Error, "Error: #{msg}"
+    end
+  end
+end

data/lib/plans/init.rb

@@ -0,0 +1,19 @@
+require 'plans/command'
+
+module Plans
+  class Init < Command
+    def do
+      plans_path = plans_pathname(options[:'plans-path'])
+      if plans_path.exist?
+        say 'The .plans directory already exists!', :red
+        say 'If you want to recreate it, you will need to manually delete it first.'
+        say 'The .plans directory is located here:'
+        say "  #{plans_path}"
+        raise_error('Plans directory exists.')
+      end
+      FileUtils.makedirs(plans_path)
+      template_path = pathname(Plans.source_root) + 'template/.'
+      FileUtils.cp_r(template_path, plans_path)
+    end
+  end
+end

data/lib/plans/list.rb

@@ -0,0 +1,47 @@
+require 'plans/command'
+require 'yaml'
+
+module Plans
+  class List < Command
+
+    def do
+      plans_path = plans_pathname(options[:'plans-path'])
+      check_plans_pathname_exists plans_path
+
+      say 'Listing all available DOC_TYPEs...'
+      say ''
+      plans_path.each_child { |x| list_template(x) }
+      say ''
+      say 'Create a new document from a template with the command `plans new DOC_TYPE`'
+    end
+
+    def list_template(path_name)
+      # must be a Pathname
+      return unless path_name.is_a? Pathname
+      # must be a directory
+      return unless path_name.directory?
+
+      doc_type = path_name.basename
+      say "DOC_TYPE: #{doc_type}"
+
+      begin
+        metadata = YAML.load_file(path_name + 'template.yml')
+        title = metadata['title'] || 'Title not found. Check template.yml.'
+        description = metadata['description'] || 'Description not found. Check template.yml.'
+        say "  Title: #{title}"
+        say "  Description: #{description}"
+      rescue Errno::ENOENT # File not found
+        say 'No template.yml found in the template directory. Did you forget to add it?', :red
+      end
+
+      unless (path_name + 'README.md').file?
+        say 'No README.md found in the template directory. Did you forget to add it?', :red
+      end
+
+      unless (path_name + 'reference.docx').file?
+        say 'No reference.docx found in template directory. Did you forget to add it?', :red
+      end
+    end
+  end
+end
+

data/lib/plans/new.rb

@@ -0,0 +1,29 @@
+require 'plans/command'
+
+module Plans
+  class New < Command
+
+    def do(doc_type)
+      plans_path = plans_pathname(@options[:'plans-path'])
+      check_plans_pathname_exists plans_path
+
+      doc_path = plans_path + doc_type
+      check_doc_path_exists(doc_path, plans_path, doc_type)
+
+      # Set the Thor::Actions destination root to the current working directory.
+      self.destination_root = '.'
+      # copy the template directory, but don't include the reference word docs.
+      directory(doc_path, "./#{doc_type}", :exclude_pattern => /docx/)
+    end
+
+    def check_doc_path_exists(doc_path, plans_path, doc_type)
+      unless doc_path.exist?
+        say "Cannot create DOC_TYPE #{doc_type} because this template does not exist.", :red
+        say 'Try `plans list` to see the available DOC_TYPEs or'
+        say 'check the templates in the .plans directory here:'
+        say "  #{plans_path}"
+        raise_error("DOC_TYPE #{doc_type} does not exist.")
+      end
+    end
+  end
+end