brief 1.9.14 → 1.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9543a0856e03eceabb57759ada882e87238d54e5
-  data.tar.gz: ceedef4e306dbf4c93fa2e92910ca89259d2a03a
+  metadata.gz: c99e43e2cb14081fa9dfb044d30bf1e21771225e
+  data.tar.gz: 75be39413bbe58d8d0169eccc6ae936223635e92
 SHA512:
-  metadata.gz: 69dd49a7a111aedafdbdef7b18c1ece2501c64916f7e0ddeccfc1a95a0593a74066146a6f484459469b811d0d2cfcfc4f0e68b520e43f2c850feaf58f66247b4
-  data.tar.gz: c7ff0f8c1549f7b74678f5925df51fd22ed5137fa9e6f1d5107f194f1442775b57bd8f662993d750d3c5b368c12970ffba13345d5324d6b4161efafafa42ae8d
+  metadata.gz: 2ee79d64d3b01159c7493672b4c7c13ad9bc7fdab0446253729fd037ed0e576a8813676e9d202ca2e26da33108dae58c1859fac7362953b689818e96c1719d0b
+  data.tar.gz: 52992dd1e843eb9259d6210fa828d50c760d6866639280d823b8b2a8581530a38b837647cc21e9464c3a33f44dc591f75a9a241fb637eece79d31cc5a052edc5

data/CHANGELOG.md

@@ -83,11 +83,11 @@ attributes.
   so for example, given a model:
 
   ```
-  define "User Story" do
+  define "Feature" do
 
   example <<- EOF
   ---
-  type: user_story
+  type: feature
   status: draft
   ---
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    brief (1.9.14)
+    brief (1.10.0)
       activesupport (~> 4.0)
       commander (~> 4.3)
       em-websocket (= 0.5.1)

data/README.md

@@ -2,20 +2,15 @@
 [![Build
 Status](https://travis-ci.org/datapimp/brief.svg?branch=master)](https://travis-ci.org/datapimp/brief)
 
-### Putting your writing to work
+### Turning writers into object oriented programmers 
 
-Brief lets writers build applications on top of collections of markdown
-files.  Brief lets you define different classes or types of documents, called
-`Model`s.  
+Brief lets writers build applications on top of collections of markdown files.  Brief lets you define different classes or types of documents, called `Model`s which are responsible for defining certain writing conventions that apply to a group of documents.
 
-These models turn the documents into objects, which can be
-used to do things such as make API calls, or publish a blog post and
-send an email campaign at the same time. 
+When documents conform to these conventions, it is possible to treat them as software entities with attributes, and give the documents and their content unique identities that can be mapped to other parts of the software systems we work with every day. 
 
 ### Turn documents into data 
 
-The most basic way of combining writing with data, is through the use of
-YAML Frontmatter as metadata for the document.  For example:
+The most basic way of combining writing with data, is through the use of YAML Frontmatter as metadata for the document.  For example:
 
 ```
 ---
@@ -34,8 +29,7 @@ This is the first paragraph.
 This is another pargraph.
 ```
 
-This YAML content at the top gets turned into data associated with the
-document. 
+This YAML content at the top gets turned into data associated with the document. 
 
 ```
 post = Post.new("/path/to/post.md") 
@@ -43,17 +37,12 @@ post.status # => 'draft'
 post.tags # => ['help','ruby']
 ```
 
-The YAML data is useful, but where the brief model system really shines
-is in the ability to extract data and metadata from the writing itself.
+The YAML data is useful, but where the brief model system really shines is in the ability to extract data and metadata from the writing itself.
 
-Each `Model` prescribes its own specific structure, usually
-in the form of heading hierarchys (h1, h2, h3, etc). Any CSS selector
-can be used against the rendered HTML produced by the markdown.  A
-model can define attributes that will be extracted from the writing, for
-example:
+Each `Model` prescribes its own specific structure, usually in the form of heading hierarchys (h1, h2, h3, etc). Any CSS selector can be used against the rendered HTML produced by the markdown.  A model can define attributes that will be extracted from the writing, for example:
 
 ```ruby
-define "Post" do
+define "Recipe" do
   content do
     title "h1:first-of-type"
     subtitle "h2:first-of-type"
@@ -61,10 +50,55 @@ define "Post" do
 
     # parses YAML blocks inside the document
     settings 'code.yaml', :serialize => true
+
+    define_section("Ingredients") do
+      each("li").is_a(:ingredient).has(:name=>"li")
+    end
+
+    define_section("Steps") do
+      each("li").is_a(:step).has(:description=>"li")
+    end
+
+    helpers do
+      def ingredient_names
+        sections.ingredients.items.map(&:name)
+      end
+
+      def have_inventory?
+        !ingredient_names.detect {|ingredient| inventory[ingredient].to_i <= 0 }
+      end
+    end
+  end
+end
+
+define "Ingredient" do
+  content do
+    title "h1:first-of-type"
+    summary "p:first-of-type"
+
+    define_section("Vendors") do
+      each("h2").is_a(:vendor).has(:title=>"h2",:website=>"a:first-of-type")
+    end
+  end
+
+  helpers do
+    def vendor_websites
+      sections.vendors.items.map(&:website)
+    end
   end
 end
 ```
 
+### Document Structure 
+
+Brief works by processing the markdown that is rendered by default, and building a hierarchal structure based on the headings you use. A `Brief::Model` can be assigned to a certain folder of documents, and if all of those documents follow the same heading structure, you can 
+interact with the documents as data structures and treat them as relatable entities in your object oriented software system.  
+
+This opens up writing as a possible user interface for a number of
+systems.  
+
+That is powerful stuff.
+
 ### Getting Started
 
 ```

data/TUTORIAL.md

@@ -109,7 +109,7 @@ which is implemented by:
 ```ruby
 # brief.rb
 
-define "User Story" do
+define "Feature" do
   meta do
     status
   end
@@ -131,12 +131,12 @@ define "User Story" do
 end
 
 action "publish user stories" do |briefcase, models, options|
-  user_stories = models
+  features = models
 
-  user_stories.each do |user_story|
-    if user_story.create_github_issue()
-      user_story.status = "published"
-      user_story.save
+  features.each do |feature|
+    if feature.create_github_issue()
+      feature.status = "published"
+      feature.save
     end
   end
 end

data/apps/blueprint/documentation/epic.md

@@ -2,6 +2,6 @@
 
 The Feature Epic model is a document that is used to document a bunch of related user stories related to a general feature category or group.
 
-For example you might have a "3rd Party Integrations" Epic which has User Stories for LinkedIn, Facebook, Github, and Twitter.  
+For example you might have a "3rd Party Integrations" Epic which has Features for LinkedIn, Facebook, Github, and Twitter.  
 
 The Epic Document can be used to describe the importance of the module as a whole at the same time that it captures the user stories.

data/apps/blueprint/documentation/user_story.md

@@ -1 +1 @@
-#### User Stories
+#### Features

data/apps/blueprint/models/epic.rb

@@ -19,18 +19,18 @@ status: draft
 
 Write a description for your epic.
 
-# User Stories
+# Features
 
-## User Story Title
+## Feature Title
 
 As a **PERSONA** I would like to **BEHAVIOR** so that I can **GOAL**
   EOF
 
   template <<-EOF
 # <%= object.title %>
-# User Stories
-<% Array(object.user_stories).each do |user_story| %>
-## <%= user_story.title %>
+# Features
+<% Array(object.features).each do |feature| %>
+## <%= feature.title %>
 As a **User** I would like to **Do this** so that I can **succeed**
 <% end %>
   EOF
@@ -40,19 +40,19 @@ As a **User** I would like to **Do this** so that I can **succeed**
     paragraph "p:first-of-type"
     paragraphs "p"
 
-    define_section "User Stories" do
+    define_section "Features" do
       each("h2").has(:title     => "h2",
                      :paragraph => "p:first-of-type",
                      :components   => "p:first-of-type strong"
                     )
 
-      each("h2").is_a :user_story
+      each("h2").is_a :feature
     end
   end
 
   helpers do
-    def user_stories
-      sections.user_stories.items.map do |item|
+    def features
+      sections.features.items.map do |item|
         item.components = Array(item.components)
 
         item.merge(goal: item.components[2],

data/apps/blueprint/models/{user_story.rb → feature.rb}

@@ -1,4 +1,4 @@
-class Brief::Apps::Blueprint::UserStory
+class Brief::Apps::Blueprint::Feature
   include Brief::Model
 
   defined_in Pathname(__FILE__)
@@ -9,7 +9,7 @@ class Brief::Apps::Blueprint::UserStory
     epic_title
   end
 
-  template :file => "user_story.md.erb"
+  template :file => "feature.md.erb"
 
   content do
     persona "p strong:first-child"

data/apps/blueprint/models/release.rb

@@ -16,7 +16,7 @@ class Brief::Apps::Blueprint::Release
     tagline "h2:first-of-type", :hide => true
     yaml_data "code.yaml:first-of-type", :serialize => :yaml, :hide => true
 
-    define_section "User Stories" do
+    define_section "Features" do
       each("h2").has(:title     => "h2",
                      :paragraph => "p:first-of-type",
                      :components   => "p:first-of-type strong"

data/lib/brief/cli/browse.rb

@@ -5,7 +5,7 @@ command 'browse documents' do |c|
   c.option '--presenter-format FORMAT', String, 'Which presenter to use?'
   c.option '--include-urls', 'Gets passed to the model renderers if present'
 
-  c.example "Browsing an arbitrary selection of documents", "brief parse ./blueprint/docs/epics ./blueprint/docs/user_stories --root=./blueprint --format json --include-rendered --include-content"
+  c.example "Browsing an arbitrary selection of documents", "brief parse ./blueprint/docs/epics ./blueprint/docs/features --root=./blueprint --format json --include-rendered --include-content"
 
   c.action do |args, options|
     options.default(root: Pathname(Brief.pwd), output_type: "array")

data/lib/brief/cli/parse.rb

@@ -7,7 +7,7 @@ command 'parse' do |c|
   c.option '--include-rendered', 'Gets passed to the model renderers if present'
   c.option '--include-urls', 'Gets passed to the model renderers if present'
 
-  c.example "Parsing an arbitrary selection of documents", "brief parse ./blueprint/docs/epics ./blueprint/docs/user_stories --root=./blueprint --format json --include-rendered --include-content"
+  c.example "Parsing an arbitrary selection of documents", "brief parse ./blueprint/docs/epics ./blueprint/docs/features --root=./blueprint --format json --include-rendered --include-content"
 
   c.action do |args, options|
     options.default(root: Pathname(Brief.pwd), output_type: "array")

data/lib/brief/document/structure.rb

@@ -1,3 +1,27 @@
+# # Structured Documents
+#
+# Normal markdown is rendered flat.  While there may be hierarchy,
+# it was difficult to parse it in a way which made the headings
+# collapsible.
+#
+# The Document Structure is responsible for grouping
+# blocks of content under their nearest previous heading element
+# acting as a parent.  It does this by wrapping them in `<section>`
+# and <article> tags, and through the use of data-attributes on the elements.
+#
+# ```
+# - h1
+#   - h2
+#     - h3
+#     - h3
+#   - h2
+# - h1
+#   - h2
+# ```
+#
+# This class allows for us to define rules based on headings, for how
+# we might interpret the meaning of the content that is written.  It allows
+# us to say: all level 2 headings are 'TodoItems' if they exist under the level 1 heading 'Tasks'
 module Brief
   class Document::Structure
     attr_accessor :fragment, :content_lines

data/lib/brief/version.rb

@@ -1,3 +1,3 @@
 module Brief
-  VERSION = '1.9.14'
+  VERSION = '1.10.0'
 end

data/spec/fixtures/example/brief.rb

@@ -24,14 +24,14 @@ define "Outline" do
   end
 end
 
-define "User Story" do
+define "Feature" do
   meta do
     title
     status :in => %w(draft published)
     epic_title
   end
 
-  template :file => "user_story.md.erb"
+  template :file => "feature.md.erb"
 
   content do
     persona "p strong:first-child"

data/spec/fixtures/example/docs/epics/epic.html.md

@@ -6,20 +6,14 @@ state: active
 ---
 
 # Blueprint Epic Example
+This is an example of an Epic Document.  An Epic is a single document which contains user stories and such.
 
-This is an example of an Epic Document.  An Epic is a single document
-which contains user stories and such.
-
-# User Stories
-
+# Features
 ## A user wants to write epics
-
 As a **User** I want to **write epics** so that I can **write a bunch of user stories in one file**
 
 ## A user wants to annotate wireframes
-
 As a **User** I want to  **annotate wireframes** so that I can **augment diagrams with targeted explanations**
 
 ## A user wants to provide details about domain concepts
-
 As a **User** I want to **provide some detailed explanations of domain concepts** so that I can **augment diagrams with targeted explanations**

data/spec/fixtures/example/docs/index.md

@@ -4,7 +4,7 @@ title: Table of Contents
 transform: true
 ---
 
-[include:content](path=user_story.html.md)
+[include:content](path=feature.html.md)
 
 # Table of contents
 

data/spec/fixtures/example/docs/user_story.html.md

@@ -1,6 +1,6 @@
 ---
-type: user_story
-title: Blueprint User Story Example
+type: feature
+title: Blueprint Feature Example
 subheading: A way of describing desired behavior of the software, from the perspective of a persona who has a goal 
 epic: Blueprint Epic Example 
 release: Blueprint Release Example

data/spec/fixtures/example/models/epic.rb

@@ -17,37 +17,37 @@ status: draft
 
 Write a description for your epic.
 
-# User Stories
+# Features
 
-## User Story Title
+## Feature Title
 
 As a **PERSONA** I would like to **BEHAVIOR** so that I can **GOAL**
   EOF
 
   template <<-EOF
 # <%= object.title %>
-# User Stories
-<% Array(object.user_stories).each do |user_story| %>
-## <%= user_story.title %>
+# Features
+<% Array(object.features).each do |feature| %>
+## <%= feature.title %>
 As a **User** I would like to **Do this** so that I can **succeed**
 <% end %>
   EOF
 
   content do
     title "h1:first-of-type"
-    define_section "User Stories" do
+    define_section "Features" do
       each("h2").has(:title     => "h2",
                      :paragraph => "p:first-of-type",
                      :components   => "p:first-of-type strong"
                     )
 
-      each("h2").is_a :user_story
+      each("h2").is_a :feature
     end
   end
 
   helpers do
-    def user_stories
-      sections.user_stories.items.map do |item|
+    def features
+      sections.features.items.map do |item|
         item.components = Array(item.components)
 
         item.merge(goal: item.components[2],

data/spec/fixtures/structures/one.html.md

@@ -16,7 +16,7 @@ This is a list:
 # SOME CODE
 ```
 
-# User Stories
+# Features
 
 ## Story Title One
 

data/spec/fixtures/structures/two.html.md

@@ -19,7 +19,7 @@ This is a list:
 # SOME CODE
 ```
 
-# User Stories
+# Features
 
 ## Story Title One
 

data/spec/lib/brief/document_spec.rb

@@ -23,7 +23,7 @@ describe "The Brief Document" do
   end
 
   it "renders html" do
-    expect(sample.to_html).to match(/h1.*User Stories.*h1\>/)
+    expect(sample.to_html).to match(/h1.*Features.*h1\>/)
   end
 
   it "renders html" do
@@ -59,7 +59,7 @@ describe "The Brief Document" do
     end
 
     it "gives me info about the section headings" do
-      expect(sample.section_headings).to include("user_stories")
+      expect(sample.section_headings).to include("features")
     end
 
     it "has the information from the sections" do
@@ -68,13 +68,13 @@ describe "The Brief Document" do
 
     it "lets me define content sections" do
       expect(sample.sections).not_to be_empty
-      expect(sample.sections.user_stories).to be_present
-      expect(sample.sections.user_stories.fragment.name).to eq("section")
-      expect(sample.sections.user_stories.fragment.css("article").length).to eq(3)
+      expect(sample.sections.features).to be_present
+      expect(sample.sections.features.fragment.name).to eq("section")
+      expect(sample.sections.features.fragment.css("article").length).to eq(3)
     end
 
     it "gives me an array of items underneath the section filled with the key value mappings i laid out" do
-      items = sample.sections.user_stories.items
+      items = sample.sections.features.items
       expect(items.length).to eq(3)
       expect(items.map(&:components).map(&:first).uniq).to eq(["User"])
     end

data/spec/lib/brief/dsl_spec.rb

@@ -5,7 +5,7 @@ describe "The Configuration DSL" do
   let(:briefcase) { Brief.testcase }
 
   it "can create methods on our models" do
-    expect(briefcase.user_stories.first.defined_helper_method).to eq(true)
+    expect(briefcase.features.first.defined_helper_method).to eq(true)
   end
 
   it "treats actions as available commands" do
@@ -13,7 +13,7 @@ describe "The Configuration DSL" do
   end
 
   it "doesnt treat helpers as available commands" do
-    expect(Brief::Epic.defined_helper_methods).to include(:user_stories)
-    expect(Brief::Epic.defined_actions).not_to include(:user_stories)
+    expect(Brief::Epic.defined_helper_methods).to include(:features)
+    expect(Brief::Epic.defined_actions).not_to include(:features)
   end
 end

data/spec/lib/brief/model_spec.rb

@@ -3,41 +3,41 @@ require "spec_helper"
 describe "The Brief Model" do
   let(:briefcase) { Brief.testcase }
   let(:epic) { briefcase.epics.first }
-  let(:user_story) { briefcase.user_stories.first }
+  let(:feature) { briefcase.features.first }
 
   it "exposes information about its schema" do
     expect(epic.class.to_schema.keys).to include(:schema, :name, :class_name, :type_alias)
   end
 
   context "DSL Style Declarations" do
-    it "picks up a definition of 'User Story'" do
-      expect(briefcase.model("User Story")).to be_present
+    it "picks up a definition of 'Feature'" do
+      expect(briefcase.model("Feature")).to be_present
     end
 
     it "defines a class for us" do
-      expect((Brief::Model::UserStory rescue nil)).to be_present
+      expect((Brief::Model::Feature rescue nil)).to be_present
     end
 
     it "shows up in the model definitions table" do
-      expect(Brief::Model.table.user_story).to be_present
+      expect(Brief::Model.table.feature).to be_present
     end
 
     it "has a definition" do
-      expect(Brief::Model::UserStory.definition).to be_a(Brief::Model::Definition)
+      expect(Brief::Model::Feature.definition).to be_a(Brief::Model::Definition)
     end
 
     it "has paths and document attributes by default" do
-      set = Brief::Model::UserStory.attribute_set.map(&:name)
+      set = Brief::Model::Feature.attribute_set.map(&:name)
       expect(set).to include(:path, :document)
     end
 
     it "has the attributes defined in the DSL" do
-      set = Brief::Model::UserStory.attribute_set.map(&:name)
+      set = Brief::Model::Feature.attribute_set.map(&:name)
       expect(set).to include(:title, :status, :epic_title)
     end
 
     it "has attribute setters" do
-      story = Brief::Model::UserStory.new
+      story = Brief::Model::Feature.new
       expect(story).to respond_to(:title=)
     end
   end
@@ -75,7 +75,7 @@ describe "The Brief Model" do
   context "Briefcase Finders" do
     it "creates methods on the briefcase for each class" do
       expect(briefcase.epics).not_to be_empty
-      expect(briefcase.user_stories).not_to be_empty
+      expect(briefcase.features).not_to be_empty
     end
 
     it "finds instances of the desired model" do
@@ -103,18 +103,18 @@ describe "The Brief Model" do
     end
 
     it "users the actions block to define CLI dispatchers (dsl)" do
-      expect(user_story.class.defined_actions).to include(:custom_action)
+      expect(feature.class.defined_actions).to include(:custom_action)
     end
 
     it "lets me define a helper method which utilizes all the extracted data and content structure" do
-      expect(epic.user_stories.length).to eq(3)
-      expect(epic.user_stories.map(&:persona)).to include("User")
+      expect(epic.features.length).to eq(3)
+      expect(epic.features.map(&:persona)).to include("User")
     end
   end
 
   context "Section Mappings" do
-    it "defines a section mapping for User Stories" do
-      mapping = epic.class.section_mapping("User Stories")
+    it "defines a section mapping for Features" do
+      mapping = epic.class.section_mapping("Features")
       expect(mapping).to be_a(Brief::Document::Section::Mapping)
     end
   end

data/spec/lib/brief/repository_spec.rb

@@ -31,8 +31,8 @@ describe "The Brief Document Repository" do
     end
 
     it "finds the last document matching a query" do
-      query = repository.where(state:"active", type:"user_story")
-      expect(query.last.type).to eq("user_story")
+      query = repository.where(state:"active", type:"feature")
+      expect(query.last.type).to eq("feature")
     end
 
     it "respects the ordering" do

data/spec/lib/brief/template_spec.rb

@@ -6,7 +6,7 @@ describe "Document Templates" do
       title: "Epic Example",
       status: "published",
       type: "epic",
-      user_stories:[{
+      features:[{
         title: "A user wants to do something",
         paragraph: "As a user I would like to do something so that I can succeed",
         goal: "I can succeed",
@@ -35,7 +35,7 @@ describe "Document Templates" do
     doc = Brief::Document.create_from_data(data)
     content = doc.content
 
-    expect(content).to include("# User Stories")
+    expect(content).to include("# Features")
     expect(content).to include("# Epic Example")
     expect(content).to include("## A user wants to do something")
     expect(content).to include("## A user wants to do something else")

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: brief
 version: !ruby/object:Gem::Version
-  version: 1.9.14
+  version: 1.10.0
 platform: ruby
 authors:
 - Jonathan Soeder
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-05-21 00:00:00.000000000 Z
+date: 2015-05-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hashie
@@ -305,6 +305,7 @@ files:
 - apps/blueprint/example/docs/diagrams/example-diagram.md
 - apps/blueprint/models/diagram.rb
 - apps/blueprint/models/epic.rb
+- apps/blueprint/models/feature.rb
 - apps/blueprint/models/milestone.rb
 - apps/blueprint/models/outline.rb
 - apps/blueprint/models/page.rb
@@ -313,7 +314,6 @@ files:
 - apps/blueprint/models/release.rb
 - apps/blueprint/models/roadmap.rb
 - apps/blueprint/models/sitemap.rb
-- apps/blueprint/models/user_story.rb
 - apps/blueprint/models/wireframe.rb
 - apps/blueprint/templates/epic.md.erb
 - apps/blueprint/templates/milestone.md.erb
@@ -521,3 +521,4 @@ test_files:
 - spec/lib/brief/template_spec.rb
 - spec/spec_helper.rb
 - spec/support/test_helpers.rb
+has_rdoc: