brief 0.0.5 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6ea809a2225dda66fa13f02a8d84815d35b1f34e
-  data.tar.gz: 746802928af37c37897c2c35ba6b48a1a70ed9ac
+  metadata.gz: 5de4de1da31d941ba973047d92612413463c2cfa
+  data.tar.gz: 9fbd98bbe85b00b6fdefabde34f79c03e6ceb6d4
 SHA512:
-  metadata.gz: 1307853ba450778aa5f929570a03f5e320385a4d383b638d2580710f05a48019dff7e00e51fe3281414255ce1aa4395c34ea8955079f51a7c781f83241e49381
-  data.tar.gz: ad898a4cdf7c2b6651e364fbc3ecdddbce7bd329481fd2c72185ed5f34f160f5c6793ff61c7eca4caf2fe7092058dbfc2d89edd7ec7b3f846dc7b0eb49e8063e
+  metadata.gz: 47d96dd1a4537378b35dc5af7f8fef84e0d80fc484497d14c90119fed09776f3274ac0b464402f858f7348f555a26e8cb45dcb9d488124ad56010ef950661d3b
+  data.tar.gz: 536970830fd8c5d7b4c4b1a3eaad68043932f5b562d07d5b714f3852db1c39eb5ba3847c4f62d056e17ab291d772d10d4f0fb1a3d3cb656d255233c540b23525

data/Gemfile

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

data/Gemfile.lock

@@ -1,79 +1,97 @@
 PATH
   remote: .
   specs:
-    brief (0.0.4)
+    brief (1.0.0)
+      activemodel
       activesupport
-      colored
       commander
+      github-fs
       hashie
-      i18n
+      inflecto
+      nokogiri
+      redcarpet
+      virtus (>= 1.0.3)
 
 GEM
   remote: https://rubygems.org/
   specs:
-    activesupport (4.1.4)
-      i18n (~> 0.6, >= 0.6.9)
+    activemodel (4.2.0)
+      activesupport (= 4.2.0)
+      builder (~> 3.1)
+    activesupport (4.2.0)
+      i18n (~> 0.7)
       json (~> 1.7, >= 1.7.7)
       minitest (~> 5.1)
-      thread_safe (~> 0.1)
+      thread_safe (~> 0.3, >= 0.3.4)
       tzinfo (~> 1.1)
-    celluloid (0.15.2)
-      timers (~> 1.1.0)
+    addressable (2.3.6)
+    axiom-types (0.1.1)
+      descendants_tracker (~> 0.0.4)
+      ice_nine (~> 0.11.0)
+      thread_safe (~> 0.3, >= 0.3.1)
+    builder (3.2.2)
     coderay (1.1.0)
-    colored (1.2)
-    commander (4.2.0)
+    coercible (1.0.0)
+      descendants_tracker (~> 0.0.1)
+    commander (4.2.1)
       highline (~> 1.6.11)
+    descendants_tracker (0.0.4)
+      thread_safe (~> 0.3, >= 0.3.1)
     diff-lcs (1.2.5)
-    ffi (1.9.3)
-    formatador (0.2.5)
-    guard (2.6.1)
-      formatador (>= 0.2.4)
-      listen (~> 2.7)
-      lumberjack (~> 1.0)
-      pry (>= 0.9.12)
-      thor (>= 0.18.1)
-    guard-rspec (4.2.10)
-      guard (~> 2.1)
-      rspec (>= 2.14, < 4.0)
-    hashie (2.1.2)
+    equalizer (0.0.9)
+    faraday (0.9.0)
+      multipart-post (>= 1.2, < 3)
+    github-fs (0.0.1)
+      activesupport (> 3.2.0)
+      octokit
+      rack
+    hashie (3.3.2)
     highline (1.6.21)
-    i18n (0.6.11)
+    i18n (0.7.0)
+    ice_nine (0.11.1)
+    inflecto (0.0.2)
     json (1.8.1)
-    listen (2.7.9)
-      celluloid (>= 0.15.2)
-      rb-fsevent (>= 0.9.3)
-      rb-inotify (>= 0.9)
-    lumberjack (1.0.7)
     method_source (0.8.2)
-    minitest (5.4.0)
-    pry (0.9.12.6)
-      coderay (~> 1.0)
-      method_source (~> 0.8)
+    mini_portile (0.6.2)
+    minitest (5.5.0)
+    multipart-post (2.0.0)
+    nokogiri (1.6.5)
+      mini_portile (~> 0.6.0)
+    octokit (3.7.0)
+      sawyer (~> 0.6.0, >= 0.5.3)
+    pry (0.10.1)
+      coderay (~> 1.1.0)
+      method_source (~> 0.8.1)
       slop (~> 3.4)
-    pry-nav (0.2.3)
-      pry (~> 0.9.10)
-    rake (10.3.2)
-    rb-fsevent (0.9.4)
-    rb-inotify (0.9.5)
-      ffi (>= 0.5.0)
-    rspec (3.0.0)
-      rspec-core (~> 3.0.0)
-      rspec-expectations (~> 3.0.0)
-      rspec-mocks (~> 3.0.0)
-    rspec-core (3.0.2)
-      rspec-support (~> 3.0.0)
-    rspec-expectations (3.0.2)
+    pry-nav (0.2.4)
+      pry (>= 0.9.10, < 0.11.0)
+    rack (1.6.0)
+    rake (10.4.2)
+    redcarpet (3.2.0)
+    rspec (3.1.0)
+      rspec-core (~> 3.1.0)
+      rspec-expectations (~> 3.1.0)
+      rspec-mocks (~> 3.1.0)
+    rspec-core (3.1.7)
+      rspec-support (~> 3.1.0)
+    rspec-expectations (3.1.2)
       diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.0.0)
-    rspec-mocks (3.0.2)
-      rspec-support (~> 3.0.0)
-    rspec-support (3.0.2)
-    slop (3.5.0)
-    thor (0.19.1)
+      rspec-support (~> 3.1.0)
+    rspec-mocks (3.1.3)
+      rspec-support (~> 3.1.0)
+    rspec-support (3.1.2)
+    sawyer (0.6.0)
+      addressable (~> 2.3.5)
+      faraday (~> 0.8, < 0.10)
+    slop (3.6.0)
     thread_safe (0.3.4)
-    timers (1.1.0)
-    tzinfo (1.2.1)
+    tzinfo (1.2.2)
       thread_safe (~> 0.1)
+    virtus (1.0.3)
+      axiom-types (~> 0.1)
+      coercible (~> 1.0)
+      descendants_tracker (~> 0.0, >= 0.0.3)
+      equalizer (~> 0.0, >= 0.0.9)
 
 PLATFORMS
   ruby
@@ -81,8 +99,6 @@ PLATFORMS
 DEPENDENCIES
   brief!
   bundler (~> 1.3)
-  guard
-  guard-rspec
   pry
   pry-nav
   rake

data/README.md

@@ -1,71 +1,172 @@
-# Brief
+# Brief 
 
-Brief is a tool to make writing markdown more productive. You can think
-of it like a preprocessor for markdown.   
+An ActiveRecord style layer on top of a folder of markdown files.
 
-Brief converts raw markdown into a nested structure which can be
-used to automate tasks and generate more specific content elements. 
+### No more dead documents 
 
-Based on which headings you use and how you nest them, brief 
-will allow you to define mappings to objects which can be used to
-automate other tasks.  
+Brief is a tool that lets you build simple applications on top of
+collections of markdown files.  The metaphor we use is a briefcase,
+which contains folders with different document types.
 
-I personally use the brief tool to allow me to take a single markdown
-file and create a project wiki page, with links to related milestones
-and github issues.
+Every document type, or model, can define a simple schema of attributes, 
+which can be specified in a YAML frontmatter preamble at the very top of
+each document.  
 
-Example:
+In addition to frontmatter metadata, you can declare other model
+attributes as CSS selectors.  For example, the very first h1 heading
+could be the title for your document, and the corresponding model for
+that document would have a `title` method which returned its value.
 
-```markdown
-# Wiki Page Heading
+This is a great way to build applications whose primary interface is the
+text editor, allowing writing and thought to flow as freely as possible
+and to later be used to power some automation tasks.
 
-Content. Will go on a wiki page.  The content below here,
-and the subheadings, will be replaced with a roll-up / summary 
-of the elements.
+**Think of it as an ActiveRecord like layer on top of a folder of
+Markdown files**.  Brief turns static text into a 'living' data object.
 
-## Milestone Heading
-
-This content will go in the milestone body.  The wiki page
-that this belongs to, will include a different kind of view of this
-content.
-
-### An issue title
-
-This goes in the issue's body. The wiki page this belongs to will
-possibly have a link to the issue and a label for its status.
-
-### Another issue title
-
-This goes in this issue's body.  Same thing. It obviously belongs to the
-milestone.
+## Getting started 
 
+```bash
+gem install brief
+mkdir blog
+cd blog 
+brief init
 ```
 
-Given the example above, I run:
+This will create a new folder for your briefcase, along with the
+following config file and structure.
 
 ```
-brief publish project overview /path/to/markdown
+- docs/
+  - an-introduction-to-brief.html.md
+- models/
+- brief.rb
 ```
 
-This will create a Github Wiki entry in the repo that I specify, and
-this wiki entry will include links to the milestones and issues. 
+The config file will look like:
+
+```ruby
+
+# configuration options for this briefcase
+config do
+  set(:models_path => Pathname(__FILE__).parent.join("models"))
+end
+
+# define a Post model
+define("Post") do
+
+  # the post model will have YAML frontmatter 
+  # with values for 'status' and 'date'
+  meta do
+    status
+    date DateTime, :default => lambda {|post, attr| post.document.created_at }
+  end
+  
+  # the post model will have a 'title' method which returns the text
+  # from the first h1 heading
+  content do
+    title "h1"
+    has_many :subheadings, "h2"
+  end
+
+  helpers do
+    def publish(options={})
+
+    end
+  end
+  
+  # Whenever we call post.save() and the status attribute changes
+  # from draft to published, do something with the model
+  on_status_change(:from => "draft", :to => "published") do |model|
+    # Do Something
+    # mail_service.send_html_email_campaign(model.to_html)
+  end
+end
+
+# this creates a custom command in the brief CLI tool
+#
+# so when you run:
+# 
+#   brief publish posts /path/to/*.html.md.
+#
+# the brief CLI will find models for the post files you reference,
+# and call whatever methods you want.
+
+action "publish posts" do |briefcase, models, options|
+
+  say "== Publishing #{ models.length } posts"
+
+  Array(models).each do |post|
+    post.publish()
+  end
+end
+```
 
-You can see a sample of this Wiki page here:
-(TODO INSERT LINK)
+### Real World Application
 
-### Publishing Briefs
+My company Architects.io, Inc. uses brief to power our Blueprint
+software.  A Blueprint is a collection of related documents that are
+used in the software architecture and design process, as well as in the
+day to day writing that takes place while building the software itself.
 
-Publishing a brief allows you to run some publishing tasks using raw
-markdown input.  
+This includes things like:
 
-(TODO) show some examples of a publisher
+- daily standups
+- bug reports
+- code reviews
+- feature epics
+- user stories
+- integration tests
+- release notes
+- wireframe annotations
 
-### Writing Briefs
+All of these things are simple markdown files.  They live in the
+projects we are working on, and by treating our writing as a structured
+exercise we are able to do a lot more things with it than just read it.
 
-Writing a brief is as easy as running the brief command, with the name
-of the template you intend to use.  It will open up $EDITOR for you with
-some example input.
+For example we can do:
 
-```bash
-brief write project overview #=> Opens up $EDITOR with some example content in it
 ```
+brief publish user stories /path/to/user-stories/*.html.md
+```
+
+which is implemented by:
+
+```ruby
+# brief.rb
+
+define "User Story" do
+  meta do
+    status
+  end
+
+  content do
+    title "h1"
+    paragraph "p:first-child"
+    persona "p:first-child strong:1st-child"
+    behavior "p:first-child strong:2nd-child"
+    goal "p:first-child strong:3rd-child"
+  end
+
+  helpers do
+    def create_github_issue
+      issue = github.create_issue(title: title, body: document.content)
+      set(issue_number: issue.number)
+    end
+  end
+end
+
+action "publish user stories" do |briefcase, models, options|
+  user_stories = models
+
+  user_stories.each do |user_story|
+    if user_story.create_github_issue()
+      user_story.status = "published"
+      user_story.save
+    end
+  end
+end
+```
+
+As you can see, Brief can be a way to make your Markdown writing efforts
+much more productive. 

data/Rakefile

@@ -1,11 +1,21 @@
 require "bundler/gem_tasks"
-require "bundler/setup"
-require "rspec/core/rake_task"
+
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
 
 Bundler::GemHelper.install_tasks
 
-RSpec::Core::RakeTask.new(:spec) do |rspec|
-  rspec.rspec_opts = ['--backtrace']
-end
+Dir[File.join(File.dirname(__FILE__), 'tasks/**/*.rake')].each {|f| load f }
+
+require 'rspec/core'
+require 'rspec/core/rake_task'
+
+desc "Run all specs in spec directory (excluding plugin specs)"
+
+RSpec::Core::RakeTask.new(:spec)
 
 task :default => :spec

data/bin/brief

@@ -1,35 +1,22 @@
 #!/usr/bin/env ruby
-#
-lib = File.join(File.dirname(__FILE__), '../lib')
-$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 
-begin
-  require "rubygems"
-  require 'colored'
-  require "commander/import"
-  require "pry"
-  require "brief"
-end
+$:.unshift File.join(File.dirname(__FILE__),'..','lib')
 
-program :name, 'Brief'
-program :version, Brief::Version
-program :description, 'Brief CLI'
+require 'rubygems'
+require 'brief'
+require 'brief/dsl'
 
-command :inspect do |c|
-  c.syntax = 'brief inspect file [options]'
-  c.description = 'Debug the parsing of a brief'
+$briefcase = Brief::Briefcase.new(root: Dir.pwd())
 
-  c.action do |args, options|
-    path = Pathname(args.first)
-    path = path.relative? ? Brief.root.join(path) : path
-    doc  = Brief::Document.new(path)
-    
-    doc.elements do |el|
-      puts el.inspect
-    end
-  end
-end
+if ARGV[0] == "console"
+  require 'pry'
+  Pry.start($briefcase)
+else
+  require 'commander/import'
+
+  program :name, "Brief"
+  program :description, "Brief makes writing markdown more productive"
+  program :version, "0.0.1"
 
-Pathname(lib).join("brief","cli","commands").children.each do |f|
-  require(File.expand_path(f)) if f.file?
+  Brief.load_commands()
 end

data/brief.gemspec

@@ -1,33 +1,39 @@
 # coding: utf-8
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'brief/version'
 
 Gem::Specification.new do |spec|
   spec.name          = "brief"
-  spec.version       = '0.0.5' 
+  spec.version       = Brief::VERSION
   spec.authors       = ["Jonathan Soeder"]
   spec.email         = ["jonathan.soeder@gmail.com"]
-  spec.description   = %q{Brief is a utility to make writing more productive for software architects. It allows you write to places like Github Wiki, The Github Issues API all from the command line and a single file.}
-  spec.summary       = %q{Brief is a utility to make writing more productive for software architects.}
-  spec.homepage      = "http://architects.io/brief"
+  spec.summary       = %q{Brief makes writing more powerful}
+  spec.description   = %q{Brief is a library for developing applications whose primary interface is the text editor}
+  spec.homepage      = ""
   spec.license       = "MIT"
 
-  spec.files         = `git ls-files`.split($/)
+  spec.files         = `git ls-files -z`.split("\x0")
   spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
-  
+
   spec.add_dependency 'hashie'
   spec.add_dependency 'commander'
-  spec.add_dependency 'colored'
+  spec.add_dependency 'github-fs'
+  spec.add_dependency 'virtus', '>= 1.0.3'
+  spec.add_dependency 'inflecto'
+  spec.add_dependency 'activemodel'
   spec.add_dependency 'activesupport'
-  spec.add_dependency 'i18n'
+  spec.add_dependency 'redcarpet'
+  spec.add_dependency 'nokogiri'
 
   spec.add_development_dependency "bundler", "~> 1.3"
   spec.add_development_dependency "rake"
-  spec.add_development_dependency "rspec"
   spec.add_development_dependency "pry"
   spec.add_development_dependency "pry-nav"
-  spec.add_development_dependency "guard"
-  spec.add_development_dependency "guard-rspec"
+  spec.add_development_dependency "rspec"
+
 end
+
+

data/examples/blog/brief.rb

@@ -0,0 +1,54 @@
+# configuration options for this briefcase
+config do
+  set(:models_path => Pathname(__FILE__).parent.join("models"))
+end
+
+# define a Post model
+define("Post") do
+
+  # the post model will have YAML frontmatter
+  # with values for 'status' and 'date'
+  meta do
+    status
+    date DateTime, :default => lambda {|post, attr| post.document.created_at }
+  end
+
+  # the post model will have a 'title' method which returns the text
+  # from the first h1 heading
+  content do
+    title "h1"
+    has_many :subheadings, "h2"
+  end
+
+  helpers do
+    def publish(options={})
+
+    end
+  end
+
+  # Whenever we call post.save() and the status attribute changes
+  # from draft to published, do something with the model
+  on_status_change(:from => "draft", :to => "published") do |model|
+    # Do Something
+    # mail_service.send_html_email_campaign(model.to_html)
+  end
+end
+
+# this creates a custom command in the brief CLI tool
+#
+# so when you run:
+#
+#   brief publish posts /path/to/*.html.md.
+#
+# the brief CLI will find models for the post files you reference,
+# and call whatever methods you want.
+
+action "publish posts" do |briefcase, models, options|
+
+  say "== Publishing #{ models.length } posts"
+
+  Array(models).each do |post|
+    post.publish()
+  end
+end
+

data/examples/blog/docs/an-intro-to-brief.html.md

@@ -0,0 +1,9 @@
+---
+type: post
+status: draft
+---
+
+# A brief introduction to brief
+
+The brief gem makes writing more productive. The time for dead documents
+is over.

data/lib/brief/briefcase.rb

@@ -0,0 +1,78 @@
+module Brief
+  class Briefcase
+    include Brief::DSL
+
+    attr_reader :options,
+                :model_definitions
+
+    def initialize(options={})
+      @options = options.to_mash
+
+      load_configuration
+      load_model_definitions
+
+      if Brief.case.nil?
+        Brief.case = self
+      end
+    end
+
+    def config
+      Brief::Configuration.instance
+    end
+
+    # Loads the configuration for this briefcase, either from the current working directory
+    # or the configured path for the configuration file.
+    def load_configuration
+      config_path = options.fetch(:config_path) do
+        root.join("brief.rb")
+      end
+
+      if config_path.exist?
+        instance_eval(config_path.read)
+      end
+    end
+
+    def load_model_definitions
+      if models_path.exist?
+        Dir[models_path.join("**/*.rb")].each {|f| require(f) }
+      end
+
+      Brief::Model.finalize
+    end
+
+    # Returns a model name by its human readable description or its type alias
+    def model(name_or_type)
+      table = Brief::Model.table
+
+      table.fetch(name_or_type) do
+        table.values.find do |k|
+          k.name == name_or_type
+        end
+      end
+    end
+
+    def root
+      Pathname(options.fetch(:root) { Dir.pwd })
+    end
+
+    def docs_path
+      root.join options.fetch(:docs_path) { config.docs_path }
+    end
+
+    def models_path
+      root.join options.fetch(:models_path) { config.models_path }
+    end
+
+    def repository
+      @repository ||= Brief::Repository.new(self, options)
+    end
+
+    def method_missing(meth, *args, &block)
+      if repository.respond_to?(meth)
+        repository.send(meth, *args, &block)
+      else
+        super
+      end
+    end
+  end
+end