brief 1.10.1 → 1.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 34377388822fff11372135724730e1748dab72e4
-  data.tar.gz: 25da9b0127fb67a0ddd85bc8f9c88069b7dc02ae
+  metadata.gz: 84967b7efa46a60164d94b566b050555cadfef37
+  data.tar.gz: 0a590d06c6fb630aa91697c3c1422858565b0e77
 SHA512:
-  metadata.gz: 954cb0e8ff81647ca21192495a65c825884076d63e95450d8afc578a30f243b417a42d1e9e941cffd6bbb647a2e4cf05fe1543c57b7392134e32a9ef95783ff1
-  data.tar.gz: 73b3977ab6e15e30dad59a52cc5c50b7b850ee56b99a9717c6ce5da908d81cdcf39fda99f0c0cfa08c2ebfe2e837f0fb60af5757a67bbed009945b194c0b7ee2
+  metadata.gz: 60e74d585fe255f2d1cc4ed0bd944abb10be2858e3d68e3ccdd848cca455aa677fd24eef39bccd298f536f248bd9666d2ca30df3d10592f8531f3c9dd5a5446d
+  data.tar.gz: acf778f8a01397e6b42c6a37621b05f4de4203f1cdeccd706d51f93c30bd7c77ddf41234c9ef0122f4f30510ab09528ebd071c5180df53eae32c6471825b85e7

data/Gemfile.lock

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

data/README.md

@@ -105,3 +105,60 @@ That is powerful stuff.
 gem install brief
 brief --help
 ```
+
+### Structure of a Briefcase
+
+- `docs/` contain diferent markdown files with YAML frontmatter.
+- `models/` define your own model classes.
+- `data/` dump data sources as JSON in here to use them in the renderer 
+- `assets/` you can include / reference assets like PNG or SVG images
+- `brief.rb` the brief config file
+
+### Servers
+
+Brief ships with a number of different "servers" which can sit on top of
+a single `briefcase` or a folder with a bunch of different briefcases.
+
+These servers provide an interface for common things like searching a
+collection of documents, rendering documents, or adding,editing,removing
+documents.
+
+Currently there is a standard REST interface, and a Websockets
+interface.
+
+### Apps
+
+The brief gem ships with a couple of `apps`.  These `apps` are
+collections of models and represent a sample application you can use.
+
+You can use an `app` by saying so in your config file:
+
+```ruby
+# brief.rb
+use "blueprint" # => $BRIEF_GEM/apps/blueprint
+```
+
+## Other neat features (TODO)
+
+### Special Link & Image Tags
+
+- You can include the content from other documents pretty easily
+
+  ```markdown
+  [include:content](path=feature.html.md)
+  ```
+
+- You can create links to other documents pretty easily
+
+  ```
+  [link:title](path=feature.html.md)
+  ```
+
+  This will find the document at the specified path, and link to it with
+  the title attribute from that document
+
+- You can inline SVG assets pretty easily:
+
+  ```markdown
+  ![inline:svg](path=diagrams/test.svg)
+  ```

data/apps/blueprint/documentation/feature.md

@@ -0,0 +1,4 @@
+#### Features
+
+Features can be used to document a single feature, link the
+relevant wireframes, mockups, concept models, diagrams, personas, or whatever else will help clarify the requirement and provide understanding behind why it is important.

data/apps/blueprint/documentation/milestone.md

@@ -1,3 +1,3 @@
 #### Milestone
 
-The milestone represents a due date for a release or delivery of software.   
+The milestone represents a due date for a release or delivery of software. Any relevant information about the milestone should go in this document.

data/apps/blueprint/documentation/mockup.md

@@ -0,0 +1,8 @@
+#### Mockups
+
+Mockups are notes that acompany a screen or user interface mockup.
+
+Mockups can include data about annotations (like x,y coordinates) which will map up with the headings of the document.
+
+This is a good way to display annotated images and talk about the
+integration points between the User Interface and the domain model.

data/apps/blueprint/documentation/page.md

@@ -1 +1,6 @@
 #### Pages 
+
+Pages are good for supplemental content that just needs to be
+displayed, or as a summary mechanism to group together a bunch of
+different more specialized rendering of the documents (e.g. a
+Diagram or a Concept model)

data/apps/blueprint/documentation/persona.md

@@ -1 +1,11 @@
 #### Personas
+
+Personas are used to help understand the different audiences for the software.  
+
+Persona models can be used in a lot of clever ways, beyond just
+describing who they are.
+
+In a set of features, there will be user stories.  User stories have a predictable structure, and because of this it is possible to query all of the user stories and filter them by persona.  
+
+This gives us a view into the product design development that is
+centered around a specific persona, which can be a very useful way to look at a set of features.

data/apps/blueprint/documentation/project.md

@@ -1 +1,7 @@
 #### Projects
+
+Any large software effort will consist of a Software Project,
+sometimes but not always represented by a single codebase or git
+repository.
+
+The blueprint itself will have many epics, features, user stories.  It will have mockups, wireframes, sitemaps.  There will be domain concepts to talk about, personas to consider, etc.  Projects are a good way to slice these up, and summarize things.

data/apps/blueprint/documentation/release.md

@@ -1 +1,7 @@
 #### Releases
+
+Releases are broadcast style message that accompany an important
+ deployment of a software project to a staging, production, or client environment.
+
+ Releases can be used to generate emails, reports, invoices, slack
+ channel announcements, whatever.

data/apps/blueprint/documentation/roadmap.md

@@ -1 +1,7 @@
 #### Roadmaps
+
+Roadmaps are a way to present a grouping of epics, or
+features, in a sequential structure.  
+
+Based on the estimates and milestones, we can generate report type
+documents about the future path we are taking.

data/apps/blueprint/documentation/sitemap.md

@@ -1 +1,7 @@
 #### Sitemaps
+
+Sitemaps should be accompanied by an ideally clickable SVG diagram.  
+
+Sitemaps are used to describe the different navigation elements, and screens that will make up a website or an application.
+
+Each screen can be associated with a Wireframe or Mockup document.

data/apps/blueprint/documentation/wireframe.md

@@ -1 +1,7 @@
-#### Wireframes
+##### Wireframes
+
+Mockups are notes that acompany a screen or user interface mockup.
+
+Mockups can include data about annotations (like x,y coordinates) which will map up with the headings of the document.
+
+This is a good way to display annotated wireframes and talk about the integration points between the User Interface and the domain model, or just provide explanation about the wireframe itself.

data/apps/blueprint/examples/concept.md

@@ -0,0 +1,16 @@
+---
+type: concept
+title: Brief Document
+---
+
+The Brief Document is a markdown file with YAML frontmatter that gets turned into document metadata.  These documents are the primary user interface for the software.
+
+# Relationships
+
+## Brief Model
+
+Based on the folder the document is in, or based on the type specified in the YAML frontmatter, a document will map to a `Brief Model`
+
+## Briefcase
+
+Every document should belong to a briefcase.  The briefcase is where the document relates to other documents, and where it gets its model rules and behaviors from.

data/apps/blueprint/examples/diagram.md

@@ -0,0 +1,32 @@
+---
+type: diagram
+title: Anatomy of a Brief Model
+attachments:
+  - diagrams/anatomy-of-a-brief-model.svg
+annotations:
+  "Annotation One": 
+    x: 400
+    y: 20
+  "Annotation Two":
+    x: 450
+    y: 20
+---
+
+![inline:svg](path=diagrams/anatomy-of-a-brief-model)
+
+Notice how we're inlining the SVG diagram.  Pretty neat.
+
+Using javascript to join the elements of the SVG to your writing is a really powerful technique for combining graphics and writing
+together in a scriptable way!
+
+# Annotations
+
+## Annotation One
+
+This can be displayed in context along with the annotation bubble for the diagram.
+
+## Annotation Two
+
+This can also be displayed in context.
+
+

data/apps/blueprint/examples/epic.md

@@ -0,0 +1,32 @@
+---
+type: epic
+title: Apps Repositories
+---
+
+# Apps Repositories
+
+The Brief project has the concept of an `app`.  An `app` is a
+collection of models that represent different templates for
+documents that you can write which can then be processed by the brief `app` in question and be used to do specific things.
+
+# Features
+
+## App Browsing
+
+- As a **writer** I would like to **view the available brief apps** so that I can **take advantage of creative writing automation ideas contributed by others**
+
+- As a **programmer** I would like to **publish my app to the
+  community repository** so that I can **share my inventions with
+  others**
+
+## Model Documentation
+
+- As a **writer** I would like to **understand the way my writing can be turned into data** so that I can **present my writing in more compelling forms** 
+
+- As a **programmer** I would like to **document the model
+  behavior** so that I can **provide a more usable interface to the writer**
+
+## Example Documents
+
+- As a **writer** I would like to **see examples of other
+  documents** so that I can **conform to the document structure**

data/apps/blueprint/examples/feature.md

@@ -0,0 +1,25 @@
+---
+type: feature
+title: App Browsing
+epic: Apps Repositories
+---
+
+# App Browsing
+
+A briefcase can be configured to use an existing "app" instead of defining all of the models and such every time.
+
+These apps can be shared over github, and can be browsed by others so that they can use the models themselves.
+
+# User Stories
+
+- As a **writer** I would like to **view the available brief apps** so that I can **take advantage of creative writing automation ideas contributed by others**
+
+- As a **programmer** I would like to **publish my app to the
+  community repository** so that I can **share my inventions with
+  others**
+
+# Wireframes
+
+- App Browser. Search Apps View
+- App Browser. App Detail View 
+

data/apps/blueprint/examples/milestone.md

@@ -0,0 +1,12 @@
+---
+type: milestone
+title: Release 1
+due_date: 2015-06-01
+number: 1
+---
+
+# Release 1
+
+This could very easily be added to Github. 
+
+We could easily join this with a release, and understand if the release was on time or not.

data/apps/blueprint/examples/mockup.md

@@ -0,0 +1,32 @@
+---
+type: mockup
+title: Anatomy of a Brief Model
+attachments:
+  - diagrams/anatomy-of-a-brief-model.svg
+annotations:
+  "Annotation One": 
+    x: 400
+    y: 20
+  "Annotation Two":
+    x: 450
+    y: 20
+---
+
+![inline:svg](path=diagrams/anatomy-of-a-brief-model)
+
+Notice how we're inlining the SVG diagram.  Pretty neat.
+
+Using javascript to join the elements of the SVG to your writing is a really powerful technique for combining graphics and writing
+together in a scriptable way!
+
+# Annotations
+
+## Annotation One
+
+This can be displayed in context along with the annotation bubble for the diagram.
+
+## Annotation Two
+
+This can also be displayed in context.
+
+

data/apps/blueprint/examples/outline.md

@@ -0,0 +1,26 @@
+---
+type: outline
+title: Table of Contents
+---
+
+# Table of Contents 
+
+- Example Documents
+  - [link:title](path=concept)
+
+    [include:summary](path=concept)
+
+  - [link:title](path=diagram)
+
+  - [link:title](path=epic)
+
+- Section One
+  - Section One A
+  - Section One B
+  - Section One C
+- Section Two
+  - Section Two A
+  - Section Two B
+  - Section Two C
+
+

data/apps/blueprint/examples/page.md

@@ -0,0 +1,10 @@
+---
+type: page
+title: Inspirations
+---
+
+# Inspirations
+
+The document mapper project.
+
+Middleman app.

data/apps/blueprint/examples/persona.md

@@ -0,0 +1,11 @@
+---
+type: persona
+title: Brief Writer
+---
+
+THe Brief Writer wants to be able to get more out of the energy they
+spend writing.  By agreeing to follow a certain structure and
+organizational template, the writer can take advantage of models that
+help turn the document into an active software object that can be used
+to power all sorts of different software powered workflows or
+presentation tools.

data/apps/blueprint/examples/project.md

@@ -0,0 +1,31 @@
+---
+type: project
+title: Brief Writing Toolkit
+status: in progress
+---
+
+# Brief Writing Toolkit
+
+This is a description of the project.
+
+This document could very easily be broken apart into much smaller,
+more focused documents, and indeed it should be.  
+
+When starting a blueprint, you might want to just start at the project
+level since often you will know ahead of time how you might structure
+the solution by project.
+
+## Dependencies
+
+- it depends on this
+- it depends on this too
+- a lot of dependencies. ugh.
+
+# Sitemap
+
+![inline:svg](path=sitemaps/brief-writer)
+
+# Personas
+
+## Persona One
+## Persona Two

data/apps/blueprint/examples/release.md

@@ -0,0 +1,28 @@
+---
+type: release
+title: Release 1
+status: delivered
+delivered_at: 2015-06-01
+environment: staging
+---
+
+# Release 1
+
+Congratulations, we almost made it.
+
+Here are the features we delivered across the various projects.  We
+need your help testing and reviewing them. 
+
+## Some Epic Title
+
+- Feature one
+- Feature two
+- Feature three
+
+## Some Other Epic Title
+
+- Feature a
+- Feature b
+- Feature c
+
+Please test these features out.

data/apps/blueprint/examples/roadmap.md

@@ -0,0 +1,25 @@
+---
+type: roadmap
+title: Brief Writing Desktop App 
+---
+
+# Milestones
+
+## Release 1
+
+Here we should be able to do x,y,z.  We will need to coordinate with
+the marketing people, and have some things drawn up by the lawyers.
+
+Here is what we expect feature wise
+
+### Some Epic Title
+
+We need these features.
+
+### Another Epic Title
+
+We also need these features.
+
+## Release 2
+
+By this point we should expect to be having actual users.

data/apps/blueprint/examples/sitemap.md

@@ -0,0 +1,19 @@
+---
+type: sitemap
+title: Brief Website Sitemap
+attachments:
+  - sitemaps/brief-website
+---
+
+![inline:svg](path=sitemaps/brief-website)
+
+
+# Screens
+
+## Home Page
+
+## Contributors Page
+
+## Browse Apps
+
+

data/apps/blueprint/examples/wireframe.md

@@ -0,0 +1,32 @@
+---
+type: wireframe
+title: Anatomy of a Brief Model
+attachments:
+  - diagrams/anatomy-of-a-brief-model.svg
+annotations:
+  "Annotation One": 
+    x: 400
+    y: 20
+  "Annotation Two":
+    x: 450
+    y: 20
+---
+
+![inline:svg](path=diagrams/anatomy-of-a-brief-model)
+
+Notice how we're inlining the SVG diagram.  Pretty neat.
+
+Using javascript to join the elements of the SVG to your writing is a really powerful technique for combining graphics and writing
+together in a scriptable way!
+
+# Annotations
+
+## Annotation One
+
+This can be displayed in context along with the annotation bubble for the diagram.
+
+## Annotation Two
+
+This can also be displayed in context.
+
+

data/apps/blueprint/models/concept.rb

@@ -0,0 +1,14 @@
+class Brief::Apps::Blueprint::Concept
+  include Brief::Model
+
+  defined_in Pathname(__FILE__)
+
+  meta do
+    title
+  end
+
+  content do
+    title "h1:first-of-type"
+    paragraph "p:first-of-type"
+  end
+end

data/apps/blueprint/models/mockup.rb

@@ -0,0 +1,15 @@
+class Brief::Apps::Blueprint::Mockup
+  include Brief::Model
+
+  defined_in Pathname(__FILE__)
+
+  meta do
+    title
+    parent_title
+    sitemap
+    project
+    category
+    tags
+    annotations Hash
+  end
+end

data/apps/blueprint/models/persona.rb

@@ -9,7 +9,6 @@ class Brief::Apps::Blueprint::Persona
 
   content do
     title "h1:first-of-type"
-    temp "h1:first-of-type"
     paragraph "p:first-of-type"
   end
 end

data/apps/blueprint/models/wireframe.rb

@@ -6,6 +6,8 @@ class Brief::Apps::Blueprint::Wireframe
   meta do
     title
     parent_title
+    sitemap
+    project
     category
     tags
     annotations Hash

data/lib/brief/model/definition.rb

@@ -9,7 +9,10 @@ module Brief
                   :defined_actions,
                   :section_mappings,
                   :template_body,
-                  :example_body
+                  :example_body,
+                  :documentation_path,
+                  :example_path,
+                  :template_path
 
     def initialize(name, options = {})
       @name             = name
@@ -66,10 +69,18 @@ module Brief
     # TODO
     # There is probably a way to inspect the filename of the code calling you
     # which would be a better way of handling this that doesn't require
-    def defined_in(filename=nil)
+    def defined_in(filename=nil, options={})
       if filename
         filename = Pathname(filename)
         @doc_options[:defined_in] = filename
+
+        self.example_path ||= options.fetch(:example_path) do
+          filename.parent.join("..","examples", filename.basename.to_s.gsub('.rb','.md'))
+        end
+
+        self.documentation_path ||= options.fetch(:documentation_path) do
+          filename.parent.join("..","documentation", filename.basename.to_s.gsub('.rb','.md'))
+        end
       end
 
       @doc_options[:defined_in]

data/lib/brief/model.rb

@@ -183,6 +183,28 @@ module Brief
         end
       end
 
+      def example_content
+        if example_path && example_path.exist?
+          return example_path.read.to_s
+        end
+
+        definition.example_body.to_s
+      end
+
+      def template_content
+        if template_path && template_path.exist?
+          return template_path.read.to_s
+        end
+
+        definition.template_body.to_s
+      end
+
+      def documentation_content
+        if documentation_path && documentation_path.exist?
+          return documentation_path.read.to_s
+        end
+      end
+
       def to_schema
         {
           schema: {
@@ -196,8 +218,8 @@ module Brief
           name: name,
           group: name.to_s.pluralize,
           actions: defined_actions,
-          example: definition.example_body.to_s,
-          template: definition.template_body.to_s,
+          example: example_content,
+          template: template_content,
           urls: {
             browse_url: "browse/#{ type_alias.to_s.pluralize }",
             schema_url: "schema/#{ type_alias }"
@@ -305,14 +327,28 @@ module Brief
         definition.send(:defined_in, *args)
       end
 
+      def template_path(*args)
+        definition.send(:template_path=, *args) unless args.empty?
+        definition.send(:template_path)
+      end
+
+      def example_path(*args)
+        definition.send(:example_path=, *args) unless args.empty?
+        definition.send(:example_path)
+      end
+
+      def documentation_path(*args)
+        definition.send(:documentation_path=, *args) unless args.empty?
+        definition.send(:documentation_path)
+      end
+
       def method_missing(meth, *args, &block)
-        # these methods when called at a class level inside of
-        # a class definition body will modify the schema settings for that model
+        # these methods have a special effect on the behavior of the
+        # model definition.  we need to make sure we call finalize after
+        # them
         if %w(meta content template example actions helpers).include?(meth.to_s)
           definition.send(meth, *args, &block)
           finalize
-        # these methods allow the model class to inspect itself and report
-        # whatever methods and actions are defined on the model class
         elsif %w(defined_helper_methods defined_actions).include?(meth.to_s)
           definition.send(meth)
         elsif meth.to_s.match(/^on_(.*)_change$/)

data/lib/brief/version.rb

@@ -1,3 +1,3 @@
 module Brief
-  VERSION = '1.10.1'
+  VERSION = '1.11.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: brief
 version: !ruby/object:Gem::Version
-  version: 1.10.1
+  version: 1.11.0
 platform: ruby
 authors:
 - Jonathan Soeder
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-05-27 00:00:00.000000000 Z
+date: 2015-05-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hashie
@@ -289,9 +289,12 @@ files:
 - Rakefile
 - TUTORIAL.md
 - apps/blueprint/config.rb
+- apps/blueprint/documentation/concept.md
 - apps/blueprint/documentation/diagram.md
 - apps/blueprint/documentation/epic.md
+- apps/blueprint/documentation/feature.md
 - apps/blueprint/documentation/milestone.md
+- apps/blueprint/documentation/mockup.md
 - apps/blueprint/documentation/outline.md
 - apps/blueprint/documentation/page.md
 - apps/blueprint/documentation/persona.md
@@ -299,14 +302,27 @@ files:
 - apps/blueprint/documentation/release.md
 - apps/blueprint/documentation/roadmap.md
 - apps/blueprint/documentation/sitemap.md
-- apps/blueprint/documentation/user_story.md
 - apps/blueprint/documentation/wireframe.md
-- apps/blueprint/example/brief.rb
-- apps/blueprint/example/docs/diagrams/example-diagram.md
+- apps/blueprint/examples/concept.md
+- apps/blueprint/examples/diagram.md
+- apps/blueprint/examples/epic.md
+- apps/blueprint/examples/feature.md
+- apps/blueprint/examples/milestone.md
+- apps/blueprint/examples/mockup.md
+- apps/blueprint/examples/outline.md
+- apps/blueprint/examples/page.md
+- apps/blueprint/examples/persona.md
+- apps/blueprint/examples/project.md
+- apps/blueprint/examples/release.md
+- apps/blueprint/examples/roadmap.md
+- apps/blueprint/examples/sitemap.md
+- apps/blueprint/examples/wireframe.md
+- apps/blueprint/models/concept.rb
 - apps/blueprint/models/diagram.rb
 - apps/blueprint/models/epic.rb
 - apps/blueprint/models/feature.rb
 - apps/blueprint/models/milestone.rb
+- apps/blueprint/models/mockup.rb
 - apps/blueprint/models/outline.rb
 - apps/blueprint/models/page.rb
 - apps/blueprint/models/persona.rb

data/apps/blueprint/documentation/user_story.md

@@ -1 +0,0 @@
-#### Features