plans 0.1.0

data/lib/plans/publish.rb

@@ -0,0 +1,98 @@
+require 'plans/command'
+
+module Plans
+  class Publish < Command
+    def do(path)
+      # Create the thumbnails first.
+      say 'Updating thumbnails.'
+      Thumbs.new(shell, options).do(path)
+
+      path = pathname(path)
+      toc_flag = options[:toc] ? "--toc" : ""
+      open_flag = options[:open]
+
+      plans_path = plans_pathname(options[:'plans-path'])
+      check_plans_pathname_exists(plans_path)
+
+      source_file = path + 'README.md'
+      check_source_file(source_file)
+
+      doc_type = get_doctype(path)
+
+      # Set the path to the reference doc for this type of document.
+      reference_docx = plans_path + doc_type + 'reference.docx'
+      check_reference_docx(reference_docx)
+
+      output_dir = path + 'publish'
+      # Make the publish directory if it does not exist.
+      FileUtils.mkdir output_dir unless Dir.exist? output_dir
+      output_file = output_dir + "#{doc_type}.docx"
+
+      # We need to set the current working directory to where the markdown file is so
+      # the images render correctly.
+      # Pandoc only looks in the current working directory.
+      Dir.chdir(path) do
+        `pandoc #{toc_flag} #{source_file} --reference-docx=#{reference_docx} --standalone -f markdown -t docx -o #{output_file}`
+      end
+
+      # Get the return code from pandoc.
+      pandoc_return = $?.to_i
+      check_pandoc_return(pandoc_return)
+
+      say "#{doc_type} published.", :green
+
+      # Open the word doc if requested
+      `open #{output_file}` if open_flag
+    end
+
+    def check_pandoc_return(pandoc_return)
+      unless pandoc_return == 0
+        say "Problem publishing #{doc_type}. (Pandoc ERR: #{pandoc_return})", :red
+        say "  #{source_file}"
+        raise_error("Pandoc ERR: #{pandoc_return}")
+      end
+    end
+
+    def check_reference_docx(reference_docx)
+      unless reference_docx.exist?
+        say 'Could not find the reference.docx for this type of file in the .plans directory.', :red
+        say 'Check to make sure that reference.docx is available here:'
+        say "  #{reference_docx}"
+        raise_error('Reference.docx not found.')
+      end
+    end
+
+    def check_source_file(source_file)
+      unless File.exist? source_file
+        say 'Markdown file to be published does not exist.', :red
+        say "  #{source_file}"
+        say 'Are you in the right directory?'
+        raise_error('README.md not found.')
+      end
+    end
+
+    # Get the document type from the YAML file next to the document.
+    #
+    # @param [Pathname] The path to the location of the template.yml file.
+    # @return [String] the type of the document found in the YAML file.
+    def get_doctype(path)
+      doc_type = nil
+      begin
+        metadata = YAML.load_file(path + 'template.yml')
+        doc_type = metadata['type']
+        if doc_type.nil?
+          say 'Type value not found. Check template.yml in the document directory', :red
+          say 'Make sure there is an entry `type: DOC_TYPE` in the file.'
+          say "  #{path}"
+          raise_error('DOC_TYPE not found in template.yml')
+        end
+      rescue Errno::ENOENT # File not found
+        say 'No template.yml found in the document directory. Did you forget to add it?', :red
+        say 'Did you run the command in the directory where the document is located?'
+        say "  #{path}"
+        raise_error('template.yml not found')
+      end
+      return doc_type
+    end
+  end
+end

data/lib/plans/thumbs.rb

@@ -0,0 +1,47 @@
+require 'plans/command'
+
+module Plans
+  class Thumbs < Command
+
+    def do(path)
+      img_path = pathname(path) + 'img'
+
+      unless img_path.exist?
+        say 'Images directory (img) does not exist.'
+        say "  #{img_path}"
+        if (yes? 'Would you like to create the directory?')
+          say 'Creating it.'
+          FileUtils.mkdir img_path
+        end
+      end
+
+      images = Dir.glob(img_path + '*.*')
+      if (images.length == 0)
+        say 'Nothing to do. No images found in img directory.', :green
+        say "  #{img_path}"
+        return
+      end
+      create_thumbnails(200, images, img_path)
+      create_thumbnails(400, images, img_path)
+      create_thumbnails(600, images, img_path)
+      say 'Thumbnails creation complete.', :green
+    end
+
+    def create_thumbnails(size, images, path)
+      target_directory = path + "#{size}px"
+      FileUtils.remove_dir target_directory if Dir.exist? target_directory
+      FileUtils.mkdir target_directory
+      FileUtils.cp images, target_directory
+      `mogrify -resize #{size} #{target_directory}/*.*`
+      # Check mogrify's return code.
+      if $?.to_i == 0
+        say "Created #{images.length} #{size}px images."
+      else
+        say "Problem creating #{size}px images. (Mogrify ERR: #{$?.to_i})", :red
+        say "  #{target_directory}"
+        raise_error("Mogrify ERR: #{$?.to_i}")
+      end
+    end
+  end
+end
+

data/lib/plans/version.rb

@@ -0,0 +1,3 @@
+module Plans
+  VERSION = "0.1.0"
+end

data/lib/plans.rb

@@ -0,0 +1,15 @@
+require 'plans/version'
+require 'plans/cli'
+require 'thor'
+
+module Plans
+
+  # Determine where gem is installed.
+  #
+  # @return The path to the gem.
+  def self.source_root
+    File.absolute_path(File.join(File.dirname(__FILE__), '..'))
+  end
+
+end
+

data/plans.gemspec

@@ -0,0 +1,31 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'plans/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "plans"
+  spec.version       = Plans::VERSION
+  spec.authors       = ["Gabriel Cook"]
+  spec.email         = ["gabe@codelever.com"]
+
+  spec.summary       = %q{Command line application for creating markdown documents from templates and publishing them in MS Word.}
+  spec.description   = %q{Command line application for creating markdown documents from templates and publishing them in MS Word.}
+  spec.homepage      = "https://github.com/code-lever/plans-gem"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.10"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "guard"
+  spec.add_development_dependency "guard-rspec"
+  spec.add_development_dependency "terminal-notifier-guard"
+  spec.add_development_dependency "aruba"
+
+  spec.add_dependency 'thor'
+end

data/template/README.md

@@ -0,0 +1,39 @@
+# Plans templates for code lever.
+
+This project contains the following document templates. 
+
+* [Vision and Scope](./scope)
+* [Functional Specifications](./functional)
+* [User Classes and Characteristics](./users)
+* [Glossary](./glossary)
+* [Plain Document](./doc)
+
+Templates are composed of a folder containing a few documents. The first is the initial version of the markdown document. This document is named *README.md*. The second is the reference document, named *reference.docx*. This is the word file used by Pandoc for style information publishing the document.
+
+## README.md
+
+When you create a new document based on this template, this file will be copied to the new document location to be used as a starting point.
+
+## reference.docx
+
+When you render the markdown document into MS Word, the styles, headers and footers of the reference.docx will be used as the basis for the published document. Modify the reference.docx to change the look and feel of the rendered document. You can, for example, add images to the header for a company logo.
+
+From [pandoc.org](http://pandoc.org/README.html)
+
+> Use the specified file as a style reference in producing a docx file. For best results, the reference docx should be a modified version of a docx file produced using pandoc. The contents of the reference docx are ignored, but its stylesheets and document properties (including margins, page size, header, and footer) are used in the new docx. If no reference docx is specified on the command line, pandoc will look for a file reference.docx in the user data directory (see --data-dir). If this is not found either, sensible defaults will be used. The following styles are used by pandoc: [paragraph] Normal, Body Text, First Paragraph, Compact, Title, Subtitle, Author, Date, Abstract, Bibliography, Heading 1, Heading 2, Heading 3, Heading 4, Heading 5, Heading 6, Block Text, Footnote Text, Definition Term, Definition, Caption, Table Caption, Image Caption, Figure, Figure With Caption, TOC Heading; [character] Default Paragraph Font, Body Text Char, Verbatim Char, Footnote Reference, Hyperlink; [table] Normal Table.
+
+You can modify the document styles and add items to the headers and footers of the *reference.docx* to customize the output. One thing to note, Pandoc seems to work best if the document is blank, so clear any text in the *reference.docx* before using it.
+
+## template.yml
+
+Metadata for the template.
+
+    # The longer title of the document
+    # Used help for plans.
+    title: User Classes and Characteristics
+
+    # A description of the document
+    # Used by help for plans.
+    description: A list of all of the users and their major characteristics. These users should be referenced by the Vision and Scope document and any associated Functional Specifications.
+
+Note that the name of the document used by plans is the name of the folder. To create the *User Classes and Characteristics* document above, you would enter the command `plans create user`.

data/template/doc/README.md

@@ -0,0 +1,12 @@
+---
+title: A Document
+subtitle: Subtitle
+---
+
+**Revision History**
+
+|Name|Date|Reason for Changes|Version|
+|----|----|------------------|-------|
+|G. Cook| July 22, 2015 | Initial draft. | v0.1 |
+
+# Overview

data/template/doc/template.yml

@@ -0,0 +1,3 @@
+type: doc 
+title: Plain Document
+description: An empty markdown document.

data/template/functional/README.md

@@ -0,0 +1,60 @@
+---
+title: <%=@project.project_name%>
+subtitle: Functional Specification - <%=@name%>
+---
+
+**Revision History**
+
+|Name|Date|Reason for Changes|Version|
+|----|----|------------------|-------|
+|G. Cook| July 22, 2015 | Initial draft. | v0.1 |
+
+# Overview
+<!-- A brief description of the feature -->
+
+# User Stories
+<!-- Repeat the following for each user story. -->
+
+## User Story
+<!--
+User stories are short, simple descriptions of a feature told from the perspective of the person who desires the new capability, usually a user or customer of the system. They typically follow a simple template:
+
+As a <type of user>, I want <some goal> so that <some reason>.
+-->
+
+### Scenarios
+<!-- Write out scenarios using Gherkin syntax.
+
+https://github.com/cucumber/cucumber/wiki/Gherkin
+
+Use Given to establish preconditions for the scenario.
+Use When to describe the key actions preformed by the user.
+Use Then to observe outcomes. In general, these will be responses form the System 
+
+Here is an example:
+
+Given some precondition
+And some other precondition
+When some action by the user type 
+And some other action
+And yet another action
+Then some testable outcome is achieved
+And something else we can check happens too
+
+Make the user one of the user types defined in the User Classes document.
+-->
+
+### Mockups
+<!-- Show each of the mockups used by the scenarios here.
+Add any additional detail about the mockup below it. For example, important validations or data types for fields.
+ -->
+
+### Confirmations
+<!-- Something the system must do that needs to have a test. A requirement that is important to the customer and must be verified. These can also be non-fuctional requirements related to the feature.
+
+Ex: Test different privacy status - private, public, unlisted. 
+-->
+
+
+
+ 

data/template/functional/template.yml

@@ -0,0 +1,3 @@
+type: functional
+title: Functional Specification 
+description: Used to describe and document a feature's intended capabilities, appearance, and user interactions.

data/template/glossary/README.md

@@ -0,0 +1,20 @@
+---
+title: <%=@project.project_name%>
+subtitle: Glossary
+---
+
+**Revision History**
+
+|Name|Date|Reason for Changes|Version|
+|----|----|------------------|-------|
+|G. Cook| July 22, 2015 | Initial draft. | v0.1 |
+
+# Glossary
+
+<!--
+Define any specialized terms that a reader needs to know to understand the document, including acronyms and abbreviations. Spell out each acronym and provide its definition. Consider building a reusable enterprise-level glossary that spans multiple projects and incorporating by reference any terms that pertain to this project.
+-->
+
+Term
+:     Definition.
+

data/template/glossary/template.yml

@@ -0,0 +1,3 @@
+type: glossary
+title: Glossary
+description: Specialized terms and abbreviations related to the project.

data/template/scope/README.md

@@ -0,0 +1,127 @@
+---
+title: <%=@project.project_name%>
+subtitle: Vision and Scope
+---
+
+**Revision History**
+
+|Name|Date|Reason for Changes|Version|
+|----|----|------------------|-------|
+|G. Cook| July 22, 2015 | Initial draft. | v0.1 |
+
+# Business Requirements
+<!-- The business requirements provide the foundation and reference for all detailed requirements development. You may gather business requirements from the customer or development organization’s senior management, an executive sponsor, a project visionary, product management, the marketing department, or other individuals who have a clear sense of why the project is being undertaken and the ultimate value it will provide, both to the business and to customers.-->
+
+## Background
+<!-- This section summarizes the rationale for the new product. Provide a general description of the history or situation that leads to the recognition that this product should be built.-->
+
+
+## Business Opportunity
+<!-- Describe the market opportunity that exists or the business problem that is being solved. Describe the market in which a commercial product will be competing or the environment in which an information system will be used. This may include a brief comparative evaluation of existing products and potential solutions, indicating why the proposed product is attractive. Identify the problems that cannot currently be solved without the product, and how the product fits in with market trends or corporate strategic directions.-->
+
+
+## Business Objectives
+<!-- Describe the important business objectives of the product in a way that is quantitative and measurable. This section should focus on the value provided to the business. This could include estimates of revenue or cost savings, return on investment analysis, or target release dates.-->
+
+##	Success Metrics
+<!-- Determine how success will be defined and measured on this project, and describe the factors that are likely to have the greatest impact on achieving that success. Include things within the direct control of the organization, as well as external factors. Establish measurable criteria to assess whether the business objectives have been met.-->
+
+## Vision Statement
+<!-- Write a concise vision statement that summarizes the purpose and intent of the new product and describes what the world will be like when it includes the product. The vision statement should reflect a balanced view that will satisfy the needs of diverse customers as well as those of the developing organization. It may be somewhat idealistic, but it should be grounded in the realities of existing or anticipated customer markets, enterprise architectures, organizational strategic directions, and cost and resource limitations.-->
+
+<!-- Here is the template suggested by Wiegers.
+For [target customer]
+Who [statement of need or opportunity]
+The [product name]
+Is [a product category]
+That [key benefit, compelling reason to buy or use]
+Unlike [primary competitive alternative, current system, or current business process]
+Our product [statement of primary differentiation and advantages of new product]
+-->
+
+## Business Risks
+<!-- Summarize the major business risks associated with developing this product, such as marketplace competition, timing issues, user acceptance, implementation issues, or possible negative impacts on the business. Estimate the severity of the risks and identify any risk mitigation actions that could be taken.-->
+
+##	Business Assumptions and Dependencies
+<!-- Record any assumptions that were made when conceiving the project and writing this vision and scope document. Note any major dependencies the project must rely upon for success, such as specific technologies, third-party vendors, development partners, or other business relationships. -->
+
+# Scope and Limitations
+<!-- The project scope defines the concept and range of the proposed solution. It’s also important to define what will not be included in the product. Clarifying the scope and limitations helps to establish realistic expectations of the many stakeholders. It also provides a reference frame against which proposed features and requirements changes can be evaluated. Proposed requirements that are out of scope for the envisioned product must be rejected, unless they are so beneficial that the scope should be enlarged to accommodate them (with accompanying changes in budget, schedule, and/or resources).-->
+
+## Major Features
+<!-- Include a numbered list of the major features of the new product, emphasizing those features  that distinguish it from previous or competing products. Specific user requirements and functional requirements may be traced back to these features.-->
+
+FE-1
+:    I'm a feature. 
+
+## Scope of Initial Release
+<!-- Describe the intended major features that will be included in the initial release of the product. Consider the benefits the product is intended to bring to the various customer communities, and generally describe the product features and quality characteristics that will enable it to provide those benefits. Avoid the temptation to include every possible feature that any potential customer category might conceivably want some day. Focus on those features and product characteristics that will provide the most value, at the most acceptable development cost, to the broadest community.-->
+
+
+## Scope of Subsequent Releases
+<!-- If a staged evolution of the product is envisioned over time, indicate which major features will be deferred to later releases.-->
+
+
+## Limitations and Exclusions
+<!-- Identify any product features or characteristics that a stakeholder might anticipate, but which are not planned to be included in the new product.-->
+
+
+
+# Business Context
+<!-- This section summarizes some of the business issues around the project, including profiles of major customer categories, assumptions that went into the project concept, and the management priorities for the project.-->
+
+## Stakeholder Profiles
+<!-- Stakeholders are individuals, groups, or organizations that are actively involved in a project, are affected by its outcome, or can influence its outcome. The stakeholder profiles identify the customers for this product and other stakeholders, and states their major interests in the product. Characterize business-level customers, target market segments, and different user classes, to reduce the likelihood of unexpected requirements surfacing later that cannot be accommodated because of schedule or scope constraints. For each stakeholder category, the profile includes the major value or benefits they will receive from the product, their likely attitudes toward the product, major features and characteristics of interest, and any known constraints that must be accommodated. Examples of stakeholder value include:
+
+
+improved productivity
+reduced rework
+cost savings
+streamlined business processes
+automation of previously manual tasks
+ability to perform entirely new tasks or functions
+conformance to current standards or regulations
+improved usability or reduced frustration level compared to current applications
+-->
+
+### Stakeholder
+
+* **Major value or benefit of the system**
+
+    *Info here*
+
+* **Attitude toward system**
+
+    *Info here* 
+
+* **Major interests**
+
+    *Info here*
+
+* **Constraints that must be accommodated**
+
+    *Info here*
+
+
+## Project Priorities
+
+<!-- Describe the priorities among the project’s requirements, schedule, and budget. The table below may be helpful in identifying the parameters around the project’s key drivers (top priority objectives), constraints to work within, and dimensions that can be balanced against each other to achieve the drivers within the known constraints. For more information, see chapter 2 of Creating a Software Engineering Culture by Karl E. Wiegers (Dorset House, 1996). Examples:-->
+
+* **Schedule**
+
+
+* **Features**
+
+
+* **Quality**
+
+
+* **Staff**
+    
+  
+* **Cost**
+
+## Operating Environment and Deployment Considerations 
+
+<!-- Summarize the information and activities that are needed to ensure an effective deployment of the solution into its operating environment. Describe the access that users will require to be able to use the system, such as whether the users are distributed over multiple time zones or located close to each other. State when the users in various locations need to access the system. If infrastructure changes are needed to support the software’s need for capacity, network access, data storage, or data migration, describe those changes. Record any information that will be needed by people who will be preparing training or modifying business processes in conjunction with deployment of the new solution.-->
+

data/template/scope/template.yml

@@ -0,0 +1,3 @@
+type: scope
+title: Vision and Scope 
+description: Define the overal vision and scope for a project.

data/template/users/README.md

@@ -0,0 +1,13 @@
+---
+title: <%=@project.project_name%>
+subtitle: User Classes and Characteristics
+---
+
+**Revision History**
+
+|Name|Date|Reason for Changes|Version|
+|----|----|------------------|-------|
+|G. Cook| July 22, 2015 | Initial draft. | v0.1 |
+
+# Overview
+<!-- A brief description of the feature -->

data/template/users/template.yml

@@ -0,0 +1,3 @@
+type: users
+title: User Classes and Characteristics
+description: A list of all of the users and their major characteristics. These users should be referenced by the Vision and Scope document and any associated Functional Specifications.