brief 1.9.11 → 1.9.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0df5a7957404e6281f7da3ea81daae61d24a2b42
-  data.tar.gz: eab76b0724000e106e08579e415570fd474a8139
+  metadata.gz: 316633c274b953b641bfba353bd834ba968a22a7
+  data.tar.gz: db0f92002cd2c63c2e44dfb89972fec21f1ea9e7
 SHA512:
-  metadata.gz: eabd297d3e1ee5ce7291156a91084a52e095aca03b798cbb1000c55fa1516c12801ceec9a8b1ec6d50f84b787057b4837d289efd67194bd967e47df262e53ae1
-  data.tar.gz: aebc6b9b3dc5974beda9cc6ca301bc0e65fd2e9009721f728258fdef68820a83660e790a6d7e454c01616e86033b18f6ed35d0129b9abb75276ef2293547dbb4
+  metadata.gz: 716128ec26d9525c7eddca5c448ff4486a95ac0aff751ba2fd33e38c99981067015e13223cf4d93a07d332a9f7ae627c9a176748117033020c634c967b639a68
+  data.tar.gz: f72905da6879984d8b52b5252024cb1e876781f2fef27c5fb43c3c732332a942ba62337c28ff530ba5e55a114b910f8dd203a3bf27fd4d92e32191cc201da061

data/CHANGELOG.md

@@ -134,3 +134,13 @@ attributes.
   - Cleaned up some implementations
   - Fully implemented the command set
   - CLI can be used to generate JSON data
+
+### 1.9.4
+  - Added support for including asset attachments inline as data
+
+### 1.9.10
+  - Added a websocket server for easy on the fly parsing / querying
+
+### 1.9.12
+  - Included ability to transform content using special markdown link syntax
+  - Included ability to inline svg assets

data/Gemfile.lock

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

data/apps/blueprint/documentation/diagram.md

@@ -1,13 +1,7 @@
-# Blueprint Diagram
+#### Blueprint Diagram
 
-The Diagram model is useful for combining notes with an SVG diagram.
+The Diagram model is useful for combining notes with an SVG diagram.  
 
-One workflow I like to use is building a UML Diagram in Google Draw, and
-exporting it as SVG.  Then using a tool like Adobe Illustrator, I will
-group the elements of the diagram, and then assign IDs and Classes to
-them.  
+One workflow I like to use is building a UML Diagram in Google Draw, and exporting it as SVG.  Then using a tool like Adobe Illustrator, I will group the elements of the diagram, and then assign IDs and Classes to them.  
 
-The Diagram document allows for a section called Annotations.  The
-Annotations section will be parsed, and treated as data.  This allows
-for rendering the diagram document, along with the diagram itself, and
-displaying the annotations in a novel way.
+The Diagram document allows for a section called Annotations.  The Annotations section will be parsed, and treated as data.  This allows for rendering the diagram document, along with the diagram itself, and displaying the annotations in a novel way.

data/apps/blueprint/documentation/epic.md

@@ -1,10 +1,7 @@
-# Feature Epics
+#### Feature Epics
 
-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.
+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 User Stories 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.
+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/milestone.md

@@ -1,4 +1,3 @@
-# Milestone
+#### 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.   

data/apps/blueprint/documentation/outline.md

@@ -1,6 +1,3 @@
-# Outline
+#### Outlines
 
-The Outline document can be used to create a summary page with links to
-a bunch of other pages.
-
-The outline model can be 
+The Outline document can be used to create a summary page with links to a bunch of other pages.

data/apps/blueprint/documentation/page.md

@@ -0,0 +1 @@
+#### Pages 

data/apps/blueprint/documentation/persona.md

@@ -0,0 +1 @@
+#### Personas

data/apps/blueprint/documentation/project.md

@@ -0,0 +1 @@
+#### Projects

data/apps/blueprint/documentation/release.md

@@ -0,0 +1 @@
+#### Releases

data/apps/blueprint/documentation/roadmap.md

@@ -0,0 +1 @@
+#### Roadmaps

data/apps/blueprint/documentation/sitemap.md

@@ -0,0 +1 @@
+#### Sitemaps

data/apps/blueprint/documentation/user_story.md

@@ -0,0 +1 @@
+#### User Stories

data/apps/blueprint/documentation/wireframe.md

@@ -0,0 +1 @@
+#### Wireframes

data/lib/brief.rb

@@ -112,6 +112,7 @@ require 'brief/document/rendering'
 require 'brief/document/front_matter'
 require 'brief/document/templating'
 require 'brief/document/content_extractor'
+require 'brief/document/transformer'
 require 'brief/document/structure'
 require 'brief/document/section'
 require 'brief/document/section/mapping'

data/lib/brief/briefcase.rb

@@ -51,24 +51,31 @@ module Brief
       end
     end
 
-    # TODO
-    # The serialization of an entire briefcase at once
-    # is important enough to be its own module
-    def as_default(params={})
-      params.symbolize_keys!
-
-      base = {
+    def info_hash
+      {
+        BRIEF_VERSION: Brief::VERSION,
         views: Brief.views.keys,
         key: folder_name.to_s.parameterize,
         name: folder_name.to_s.titlecase,
         settings: settings,
         cache_key: cache_key,
         root: root.to_s,
-        docs_path: docs_path.to_s,
-        assets_path: assets_path.to_s,
-        models_path: models_path.to_s,
-        data_path: data_path.to_s
+        paths:{
+          docs_path: docs_path.to_s,
+          assets_path: assets_path.to_s,
+          models_path: models_path.to_s,
+          data_path: data_path.to_s
+        }
       }
+    end
+
+    # TODO
+    # The serialization of an entire briefcase at once
+    # is important enough to be its own module
+    def as_default(params={})
+      params.symbolize_keys!
+
+      base = info_hash
 
       if params[:include_data] || params[:data]
         base[:data] = data.as_json
@@ -93,7 +100,10 @@ module Brief
 
         all = all_models.compact
 
-        base[:models] = all.map {|m| m.as_json(model_settings) }
+        base[:models] = all.map do |m|
+          m.document.refresh! if params[:refresh_models]
+          m.as_json(model_settings)
+        end
       end
 
       base
@@ -104,6 +114,7 @@ module Brief
                              rendered: true,
                              models: true,
                              schema: true,
+                             documentation: true,
                              attachments: true)
       as_default(options)
     end

data/lib/brief/document.rb

@@ -270,17 +270,37 @@ module Brief
       super || (data && data.respond_to?(method)) || (data && data.key?(method))
     end
 
+    # The structure analyzer of the document is responsible for grouping
+    # the content under the headings by wrapping them in divs, and creating
+    # relationships between the nodes. This is what lets us provide an easy
+    # iteration API on top of the parsed document
     def structure
       @structure_analyzer ||= Brief::Document::Structure.new(fragment, raw_content.lines.to_a)
     end
 
+    # The Parser wraps the rendered HTML in a nokogiri element so we can easily manipulate it.
+    # Prior to doing so, we use the structure analyzer to build more metadata into the markup
     def parser
       @parser ||= begin
                     structure.prescan
-                    structure.create_wrappers
+
+                    structure.create_wrappers.tap do |f|
+                      transformer_for(f).all if data.transform
+                    end
                   end
     end
 
+    # The transformer is responsible for performing content modifications
+    # on the rendered document.  This is useful for supporting extensions that
+    # are driven by the markdown language.
+    #
+    # TODO: This is hidden behind a feature flag, and requires the document
+    # to have metadata that specifies transform = true
+    def transformer_for(doc_fragment=nil)
+      doc_fragment ||= fragment
+      @transformer ||= Brief::Document::Transformer.new(doc_fragment, self)
+    end
+
     def fragment
       @fragment ||= Nokogiri::HTML.fragment(to_raw_html)
     end

data/lib/brief/document/rendering.rb

@@ -1,16 +1,10 @@
 module GitHub
   class Markdown
-
     def self.render_gfm(content)
-      html = self.to_html(content, :gfm)
-      html = add_level_and_heading(html)
-      html
-    end
-
-    def self.add_level_and_heading(html)
-      html.gsub(/<h([1-6])>(.+?)<\/h\1>/,"<h\\1 data-level='\\1' data-heading='\\2'>\\2<\/h\\1>")
+      self.to_html(content, :gfm).tap do |html|
+        html.gsub!(/<h([1-6])>(.+?)<\/h\1>/,"<h\\1 data-level='\\1' data-heading='\\2'>\\2<\/h\\1>")
+      end
     end
-
   end
 end
 

data/lib/brief/document/transformer.rb

@@ -0,0 +1,77 @@
+module Brief
+  class Document::Transformer
+    attr_reader :document, :fragment
+
+    def initialize(fragment, document)
+      @fragment = fragment
+      @document = document
+    end
+
+    def all
+      transform_dynamic_links
+      inline_svg_content
+    end
+
+    def inline_svg_content
+      inline_svg_images.each do |img|
+        _, value = img['src'].to_s.split("=")
+
+        if asset = document.briefcase.find_asset(value)
+          img.replace("<div class='svg-wrapper'>#{ asset.read }</div>")
+        end
+      end
+    end
+
+    def transform_dynamic_links
+      dynamic_link_elements.each do |node|
+        attribute, value = node['href'].to_s.split("=")
+        instruction, strategy = node.text.to_s.split(':')
+
+        if instruction == "link" && attribute == "path"
+          begin
+            link_to_doc = document.briefcase.document_at(value)
+            text = link_to_doc.send(strategy)
+            node.inner_html = text
+            node['href'] = "brief://#{ link_to_doc.path }"
+          rescue
+            nil
+          end
+        end
+      end
+
+      include_link_elements.each do |node|
+        attribute, value = node['href'].to_s.split("=")
+        instruction, strategy = node.text.to_s.split(':')
+
+        if instruction == "include" && attribute == "path"
+          include_doc = document.briefcase.document_at(value)
+
+          replacement = nil
+
+          if strategy == "raw_content"
+            replacement = include_doc.unwrapped_html
+          elsif strategy == "content"
+            replacement = include_doc.to_html
+          end
+
+          node.replace(replacement) if replacement
+        end
+      end
+    end
+
+    private
+
+    def inline_svg_images
+      fragment.css('img[alt="inline:svg"]')
+    end
+
+    def dynamic_link_elements(needle="link:")
+      fragment.css('a:contains("' + needle + '")')
+    end
+
+    def include_link_elements
+      dynamic_link_elements("include:")
+    end
+  end
+end
+

data/lib/brief/dsl.rb

@@ -10,6 +10,7 @@ module Brief
       Brief.views[name.to_sym] = block
     end
 
+    # Extends an existing class
     def extend(*args, &block)
       options     = args.dup.extract_options!
       name        = args.first
@@ -27,6 +28,7 @@ module Brief
       klass.definition.validate!
     end
 
+    # defines a new model class
     def define(*args, &block)
       options     = args.dup.extract_options!
       name        = args.first

data/lib/brief/model.rb

@@ -142,18 +142,48 @@ module Brief
             rendered: model_doc.rendered
           }
         else
-          {
-          }
+          { }
+        end
+      end
+
+      def content_schema_summary
+        base = definition.content_schema.attributes
+
+        base.keys.inject({}) do |memo, key|
+          val = base[key]
+          args = Array(val[:args])
+          first = args.first
+          memo[key] = first if first
+          memo
+        end
+      end
+
+      def metadata_schema_summary
+        base = definition.metadata_schema
+
+        base.keys.inject({}) do |memo, key|
+          val = base[key]
+          args = Array(val[:args])
+          first = args.first.to_s
+
+          if args.length == 1 && first == key.to_s
+            memo[key] = "string"
+          elsif args.length >= 2
+            memo[key] = args.last
+          end
+
+          memo
         end
       end
 
       def to_schema
         {
           schema: {
-            content: definition.content_schema,
-            metadata: definition.metadata_schema,
+            content: content_schema_summary,
+            metadata: metadata_schema_summary,
           },
           documentation: to_documentation,
+          defined_in: defined_in,
           class_name: to_s,
           type_alias: type_alias,
           name: name,

data/lib/brief/version.rb

@@ -1,3 +1,3 @@
 module Brief
-  VERSION = '1.9.11'
+  VERSION = '1.9.12'
 end

data/spec/fixtures/example/brief.rb

@@ -18,6 +18,12 @@ define "Release" do
   end
 end
 
+define "Outline" do
+  meta do
+    title
+  end
+end
+
 define "User Story" do
   meta do
     title

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

@@ -1,10 +1,6 @@
 ---
 type: concept
-
+needle: bw3bg25pgdk1dmlcc0i7vgfx8azujn0k7p17
 ---
 
-# Modified Content sorqvyr5bygiotiqfp2jnj3ku0k240xhv8uf
-
-1
-
-1
+# Modified Content v4lk5hmstxxb5abwdg1txe5utwwasdwhdhid

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

@@ -1,10 +1,16 @@
 ---
 type: outline
+title: Table of Contents
+transform: true
 ---
 
+[include:content](path=user_story.html.md)
+
 # Table of contents
 
 ## Personas
+  - [link:title](path=persona.html.md)
+
 ## Epics
 ## Wireframes
 ## Concepts

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

@@ -2,4 +2,7 @@
 type: wireframe
 title: Blueprint Wireframe Example
 subheading: A key concept to the domain model 
+transform: true
 ---
+
+![inline:svg](path=diagrams/test.svg)

data/spec/lib/brief/apps_spec.rb

@@ -11,7 +11,7 @@ describe "Packaged Apps" do
 
   it "renders documentation for the app" do
     rendered = blueprint.render_documentation.epic.rendered
-    expect(rendered).to include("h1")
+    expect(rendered).to include("Feature Epics")
   end
 
   it "should find the right path for an app name" do

data/spec/lib/brief/content_transformation_spec.rb

@@ -0,0 +1,18 @@
+require "spec_helper"
+
+describe "Content Transformation" do
+  let(:outline) { Brief.testcase.document_at("index.md") }
+  let(:wireframe) { Brief.testcase.document_at("wireframe.html.md") }
+
+  it "transforms the link tags based on the DSL" do
+    html = outline.to_html
+    expect(html).to include("Blueprint Persona Example")
+    expect(html).to include("brief://")
+  end
+
+  it "automatically inlines SVG content for us" do
+    html = wireframe.to_html
+    expect(html).to include("svg-wrapper")
+    expect(html).to include("svg version")
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: brief
 version: !ruby/object:Gem::Version
-  version: 1.9.11
+  version: 1.9.12
 platform: ruby
 authors:
 - Jonathan Soeder
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-05-13 00:00:00.000000000 Z
+date: 2015-05-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hashie
@@ -353,6 +353,7 @@ files:
 - lib/brief/document/section/mapping.rb
 - lib/brief/document/structure.rb
 - lib/brief/document/templating.rb
+- lib/brief/document/transformer.rb
 - lib/brief/document_mapper.rb
 - lib/brief/dsl.rb
 - lib/brief/model.rb
@@ -404,6 +405,7 @@ files:
 - spec/lib/brief/apps_spec.rb
 - spec/lib/brief/attachments_spec.rb
 - spec/lib/brief/briefcase_spec.rb
+- spec/lib/brief/content_transformation_spec.rb
 - spec/lib/brief/data_spec.rb
 - spec/lib/brief/document_spec.rb
 - spec/lib/brief/dsl_spec.rb
@@ -499,6 +501,7 @@ test_files:
 - spec/lib/brief/apps_spec.rb
 - spec/lib/brief/attachments_spec.rb
 - spec/lib/brief/briefcase_spec.rb
+- spec/lib/brief/content_transformation_spec.rb
 - spec/lib/brief/data_spec.rb
 - spec/lib/brief/document_spec.rb
 - spec/lib/brief/dsl_spec.rb