eyemask 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 03c52d9ed9335e41ef52c481dfad96e062857de4
+  data.tar.gz: bf47ffad66e00a3eea12fcf3bdb929c66d102527
+SHA512:
+  metadata.gz: 4fc4cda7e0efcfa08b338440ba94546b70f57d5cbe3b57d462fc8b2e80e89a3e4e70cc233b4e078f4dd33507aaddc61c31ba040406fcb9abe004ffd2b6c3a2cb
+  data.tar.gz: 526683ab490a3d6aa6ec514c714949b716b6e5b26ed415612aecc91fc95f0500ce43e855bd9c835aa2461b119b8a3bbe0ec49adf35d52c8c80546a328b0a2bfa

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,8 @@
+language: ruby
+cache: bundler
+
+rvm:
+  - 2.2.0
+
+script: 'bundle exec rake'
+ 

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,13 @@
+# Contributor Code of Conduct
+
+As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free experience for everyone, regardless of level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, age, or religion.
+
+Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct. Project maintainers who do not follow the Code of Conduct may be removed from the project team.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by opening an issue or contacting one or more of the project maintainers.
+
+This Code of Conduct is adapted from the [Contributor Covenant](http:contributor-covenant.org), version 1.0.0, available at [http://contributor-covenant.org/version/1/0/0/](http://contributor-covenant.org/version/1/0/0/)

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Joe Geldart
+
+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,117 @@
+# Eyemask
+
+Eyemask allows you to generate rich documentation from your Cucumber specs. It works by taking the output of the JSON formatter and applying a [Liquid](http://liquidmarkup.org/) template to it. The result can be as simple as a plain text or Markdown file, or as complex as an HTML file ready to be rendered into PDF.
+
+The purpose of Eyemask is to make it easy to maintain living documentation that can be used by the whole team -- from developers to designers to client stakeholders -- no matter whether they're more verbal or visual. It is based on some of the ideas of [Rich Pictures](http://en.wikipedia.org/wiki/Rich_picture) from soft systems research.
+
+Eyemask assumes that the description blocks for features and scenarios (the plain text before any other content) are marked up using a variant of Markdown. We support running those blocks through Liquid, to allow template authors to use a powerful set of tags. These tags include `{% uml %}`, allowing you to embed UML diagrams using [PlantUML's syntax](http://plantuml.sourceforge.net/index.html).
+
+This tool is still in its early days, and will evolve substantially as it is used in the wild. Please help us improve it by submitting feature requests, bug reports, and pull requests.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'eyemask'
+```
+
+Or, for the latest development version:
+
+```ruby
+gem 'eyemask', git: 'https://github.com/wearefriday/eyemask'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install eyemask
+
+## Usage
+
+Eyemask is designed to be used as part of a larger toolchain. Its most basic operation takes a JSON file and outputs a Markdown file to `STDOUT`.
+
+    $ bundle exec eyemask process cucumber.json
+
+We also support taking the JSON from `STDIN` by using `-` as the file name:
+
+    $ cat cucumber.json | bundle exec eyemask process -
+
+You can specify a custom template by providing the `--template` option:
+
+    $ bundle exec eyemask process cucumber.json --template="path/to/template.html"
+
+There are also some more built-in templates that can be used by refering to their name. For example, the [Prince XML](http://www.princexml.com/) template can be invoked as follows:
+
+    $ bundle exec eyemask process cucumber.json --template=princexml
+
+It also supports customisation via *parameters*. There are four primary parameters: title, subtitle, logo, and authors. These become top-level variables available to the template:
+
+    $ bundle exec eyemask process cucumber.json --title="My Title Here"
+
+You can also set custom parameters by passing a `--params` option. The parameters take the form 'key':'value':
+
+    $ bundle exec eyemask process cucumber.json --params=my_param:"My Value" my_other_param:2
+
+This list of options is likely to grow as we expand the use-cases of the tool.
+
+## Coming soon
+
+Here are some of the features that are planned for the future (in no particular order):
+
+- More and improved named default templates to make Eyemask more powerful out of the box.
+
+- Additional explanatory materials as Markdown files to explain more about your code.
+
+- Providing textual syntaxes for more diagram types, including charts, for when you want to reduce the cost of change.
+
+- Tags for footnotes, pullquotes, sidebars, and sidenotes. 
+
+- Index and flexible, configurable Table of Contents generation (probably based on a similar 'two-pass' approach as used by LaTeX).
+
+- Default metadata, such as the date and time of preparation.
+
+- Additional standard metadata params, such as version, client, project, and copyright.
+
+- A new textual syntax and diagram renderer for 'scenario flow diagrams' allowing links from blocks to scenarios or individual steps.
+
+- A construct/tag for cross-references of scenarios, features, etc.
+
+- Implement support for backgrounds and scenario outlines (with variable highlighting) in the default templates
+
+## UML diagrams
+
+Eyemask supports rich UML diagrams, for those occasions when a visual is the best way to explain a feature. This uses the [PlantUML](http://plantuml.sourceforge.net/index.html) command-line tool. To use this functionality, download the PlantUML JAR and create a shell script called `plantuml`, in your `PATH`, that executes the JAR passing all parameters.
+
+## Standard templates
+
+Eyemask currently includes 3 different standard templates that can be used by providing their name to the `--template` option:
+
+- `--template=markdown` -- Produces a Markdown file that can be provided to tools such as Pandoc.
+- `--template=princexml` -- A traditional 'book' template designed for use with PrinceXML.
+- `--template=slides` -- A clean presentation template designed for use with PrinceXML.
+
+These templates are being tweaked and improved. Other templates will likely be added over time.
+
+## Making PDFs
+
+This tool produces text files. These can be converted to nice PDFs using a few different tools. If you're producing your specifications for non-commercial uses, or have a licence, [Prince XML](http://www.princexml.com/) produces a very high quality of output. You can pipe the output of Eyemask directly into PrinceXML using a command such as:
+
+    $ bundle exec cucumber --format json | bundle exec eyemask process - --template=slides | prince -o tmp/specification.pdf -
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, 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` to create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+1. Fork it ( https://github.com/wearefriday/eyemask/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request

data/Rakefile

@@ -0,0 +1,35 @@
+require 'bundler/gem_tasks'
+
+begin
+  require 'rspec/core/rake_task'
+  require 'cucumber'
+  require 'cucumber/rake/task'
+
+  # Default directory to look in is `/specs`
+  # Run with `rake spec`
+  RSpec::Core::RakeTask.new(:specs) do |task|
+    task.rspec_opts = ['--color']
+  end
+
+  Cucumber::Rake::Task.new(:features) do |t|
+    t.cucumber_opts = "--format progress"
+  end
+
+  rescue LoadError
+
+  desc 'RSpec rake task not available'
+  task :specs do
+    abort 'RSpec rake task is not available. Be sure to install RSpec as a gem or plugin'
+  end
+
+  desc 'Cucumber rake task not available'
+  task :features do
+    abort 'Cucumber rake task is not available. Be sure to install cucumber as a gem or plugin'
+  end
+
+end
+
+task :test => [:build,:install,:specs, :features]
+
+
+task :default => :test

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "eyemask"
+
+# 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/document

@@ -0,0 +1,5 @@
+#!/bin/bash
+
+set -euo pipefail
+
+bundle exec cucumber --format json | eyemask process - --subtitle="Eyemask Specification" --title="Friday" --authors="Joe Geldart" --template=slides | prince -o tmp/eyemask.pdf -

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/eyemask

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+
+require "eyemask"
+
+Eyemask::App.start

data/eyemask.gemspec

@@ -0,0 +1,33 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'eyemask/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "eyemask"
+  spec.version       = Eyemask::VERSION
+  spec.authors       = ["Joe Geldart"]
+  spec.email         = ["joe.geldart@wearefriday.com"]
+
+  spec.summary       = %q{Eyemask makes it easy to create rich, engaging, living documentation that everyone can use.}
+  spec.homepage      = "http://github.com/wearefriday/eyemask"
+  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.8"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "cucumber", "~> 1.1.1"
+  spec.add_development_dependency "aruba", "~> 0.6.2"
+  spec.add_development_dependency "rspec", "~> 3.2"
+  spec.add_development_dependency "pry"
+  spec.add_development_dependency "pry-byebug"
+  spec.add_runtime_dependency "multi_json", "~> 1.11.0"
+  spec.add_runtime_dependency "thor", "~> 0.19.1"
+  spec.add_runtime_dependency "redcarpet", "~> 3.2.2"
+  spec.add_runtime_dependency "liquid", "~> 3.0.1"
+  spec.add_runtime_dependency "rouge"
+end

data/lib/eyemask.rb

@@ -0,0 +1,4 @@
+require "eyemask/version"
+require "eyemask/app"
+require "eyemask/core"
+require "eyemask/liquid"

data/lib/eyemask/app.rb

@@ -0,0 +1,42 @@
+require "thor"
+
+module Eyemask
+
+  class App < Thor
+
+    desc "process", "Process one or more Cucumber JSON files to Markdown"
+    method_option "title", desc: "Set a custom title for the document", default: "Specification"
+    method_option "subtitle", desc: "Set a custom subtitle for the document"
+    method_option "authors", desc: "Set a list of authors for the document", type: :array, default: []
+    method_option "logo", desc: "Provide a URL for a logo that can be used in templates"
+    method_option "template", desc: "A custom Liquid template for rendering the output", default: "markdown"
+    method_option "params", desc: "A set of custom parameters coded as key:value", type: :hash, default: {}
+    def process(*file_names)
+      init_opts = {}
+      loader = Eyemask::Core::Loader.new(options)
+      file_names.each do |file|
+        loader.load(file, contents(file))
+      end
+      loader.done
+      
+      init_opts[:template] = options[:template]
+
+      puts Eyemask::Core::Converter.new(init_opts).convert(loader.document)
+    end
+
+    no_commands do
+
+      def contents(file_name)
+        case file_name
+        when "-"
+          STDIN.read
+        else
+          File.open(file_name).read
+        end
+      end
+
+    end
+
+  end
+
+end

data/lib/eyemask/core.rb

@@ -0,0 +1,2 @@
+require "eyemask/core/loader"
+require "eyemask/core/converter"

data/lib/eyemask/core/converter.rb

@@ -0,0 +1,37 @@
+require 'json'
+require 'liquid'
+
+module Eyemask
+  module Core
+    class Converter
+
+      def initialize(initiaizer_options={})
+        @template = ::Liquid::Template.parse(template(initiaizer_options[:template]))
+      end
+
+      def convert(document)
+        @template.render(document, registers: document).strip
+      end
+
+      private
+
+      def template(template)
+        case template
+        when "markdown"
+          File.open(template_file("markdown.md")).read
+        when "princexml"
+          File.open(template_file("princexml.html")).read
+        when "slides"
+          File.open(template_file("slides.html")).read
+        else
+          File.open(File.expand_path(template)).read
+        end
+      end
+
+      def template_file(filename)
+        File.join(File.dirname(File.expand_path(__FILE__)), "../../../templates/#{filename}")
+      end
+
+    end
+  end
+end

data/lib/eyemask/core/loader.rb

@@ -0,0 +1,47 @@
+module Eyemask
+  module Core
+
+    class Loader
+
+      def initialize(options={})
+        @options = options
+        @contents = []
+      end
+
+      def load(uri, data)
+        @contents.concat(to_elements(uri, data))
+      end
+
+      def done
+        # DO NOTHING, HERE AS A HOOK
+      end
+
+      def document
+        doc = {}
+        doc["contents"] = contents
+        doc["title"] = @options[:title]
+        doc["subtitle"] = @options[:subtitle]
+        doc["authors"] = @options[:authors]
+        doc["logo"] = @options[:logo]
+        doc["params"] = @options[:params]
+        doc
+      end
+
+      def contents
+        @contents.sort{|a, b| a["uri"] <=> b["uri"] }
+      end
+
+      private
+
+      def to_elements(uri, data)
+        begin
+          JSON.parse(data)
+        rescue JSON::ParserError
+          []
+        end
+      end
+
+    end
+
+  end
+end