brief 1.17.9 → 1.17.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: faf6fee908cd26f6c56e6b7666a69a54cdd485c4
-  data.tar.gz: 601462587977651e9c5836442448cc18a71030b9
+  metadata.gz: 29b72df28a6667259acc1ee62242da76037e02fa
+  data.tar.gz: bbd15b759f0b16bfd3f70fd3cf323f35133db188
 SHA512:
-  metadata.gz: 07b3796eecb3fa04b0368696d0dc83e337af1e9b0c4d037d13bb10e23f228330e9dbc85158eb3f107dff2c3479ab88e7b9c75c0bac3740a69a665f1a9bac2085
-  data.tar.gz: 538b9687ac9dbe8b1a240fee5484ab417347c802b9a7e37c8f0e1886b397eeda94d4eb01a11c10c404c718cc44a090a28195bb38f785dfe735deea308fb9c9e8
+  metadata.gz: 73d62db93d1df6b6c47fcac79acdd1ee12b8a77f0752fe2731e5632b2060074cecc2d04630c5f72ef26f5431e52cae10ba8b0cdde19a8671a51c05610fcb81a2
+  data.tar.gz: b48a215e6ecfef573bb611f0423546db4f0298efddaac410104884b266dc07d557568ac57b323c1e6fd06f978f3bec6d0dee1c0b3eeb841fddf7be353f64d481

data/apps/blueprint/extensions/middleman.rb

@@ -15,7 +15,7 @@
         patterns = [
           '.png',  '.gif', '.jpg', '.jpeg', '.svg', # Images
           '.eot',  '.otf', '.svc', '.woff', '.ttf', # Fonts
-          '.js', '.slim', '.erb', '.md',                                    # Javascript
+          '.js', '.slim', '.erb', '.md', '.psd'                                    # Javascript
         ].map { |e| File.join(blueprint.assets_path, "**", "*#{e}" ) }
 
         sprockets.prepend_path(blueprint.assets_path)

data/docs/advanced-features.md

@@ -0,0 +1,3 @@
+# Advanced Features
+
+Here I'll cover advanced features such as YAML serialization. 

data/docs/application-interfaces.md

@@ -0,0 +1,4 @@
+# Application Interfaces
+
+Here I'll document the REST Interface and the Websocket Interface for
+the Brief Gem.

data/docs/brief-apps.md

@@ -0,0 +1,5 @@
+# Brief Apps
+
+Here I'll talk about the concept of the Brief app as a tool for defining
+re-usable model definitions that can be documented, shipped with
+examples, templates, and other useful features. 

data/docs/brief-cli.md

@@ -0,0 +1,5 @@
+# Brief Command Line Interface
+
+Here I'll describe the way the Brief gem lets use manipulate documents
+or render them and export them in other formats using the built in
+command line interface.

data/docs/brief-model-classes.md

@@ -0,0 +1,4 @@
+# Brief Models
+
+Here I'll document the behavior of the Brief Model, and specific
+settings.

data/docs/briefcase-folder-structure.md

@@ -0,0 +1,3 @@
+# Briefcase Structure
+
+Here I'll talk about the organization structure within a briefcase, including how documents are organized and how assets can be included.

data/docs/briefcase-renderers.md

@@ -0,0 +1,5 @@
+# Briefcase Renderers
+
+Here I'll discuss the use of different rendering systems for a
+briefcase, such as a middleman application, react.js application, or a
+PDF

data/docs/index.md

@@ -0,0 +1,15 @@
+# Brief Documentation
+
+- Intro
+- Briefcase Folder Structure 
+- Brief Model Classes
+- Briefcase Document Structure
+- Brief Command Line Interface
+- Views and Commands 
+- Markdown Extensions
+- Brief Apps
+- Briefcase Renderers
+- Application Interfaces
+- Advanced Features
+- Real world examples
+

data/docs/intro.md

@@ -0,0 +1,122 @@
+# A Brief Introduction to Brief 
+
+Brief provides an object / relational data layer on top of collections of markdown documents.  
+
+It lets you use normal writing that occurs in files and folders with a person's favorite text editor 
+as your application's main user interface.
+
+A Briefcase is a folder which contains Markdown documents.  These
+Markdown documents may contain YAML Frontmatter and/or Github Flavored
+Markdown.  
+
+Through either the `type` value that is specified as YAML in the header, 
+or through the name of the folder it belongs to, a document can be
+assigned a specific `Brief::Model` class which can give the document  
+and writing the same kind of special powers we give to a row in a SQL
+table.
+
+### What is a Brief Model
+
+The Model class acts as a specification for that type of document.  
+
+The specification defines the metadata it expects to see, and the
+general structure the document should follow.  It then lets the
+programmer treat each individual document as an object, and do whatever
+you want with it.
+
+A document turned into a Brief object model will determine its state and
+attributes in one of two ways:
+
+1) YAML Frontmatter that gets embedded in the header of the document
+2) Content extracted from the rendered markdown using a system of simple
+   CSS selectors
+
+### Why is this valuable?
+
+I think this is great because a collection of markdown documents that
+exists on Github is more than sufficient as a database of record for a
+lot of different projects, and you get a lot of great features this way
+for free such as audit trails, branching, discussions, task management,
+etc.
+
+Blogs are the most obvious example, but using Brief to write your blog
+would be overkill.  Brief is made to power much more ambitious kinds of
+applications, and making it easier to use text editors and written
+language as one of the primary interfaces.
+
+### An Example Brief Model
+
+```ruby
+class Post
+  include Brief::Model
+  
+  meta do
+    title
+    subtitle
+    status :default => "draft"
+  end
+
+  content do
+    title "h1:first-of-type"
+    subtitle "h2:first-of-type"
+    excerpt "h3#excerpt p", hide: true
+  end
+
+  actions do
+    def publish
+      set(state:"published", published_at: Time.now)
+      save
+    end
+  end
+end
+```
+
+In this specification for the `Post` model, we declared some acceptable
+values in the YAML frontmatter, such as the title and subtitle of the
+post. 
+
+We also say that the same values can be extracted from the document's h1
+and h2 tags.
+
+An example document might look like:
+
+```markdown
+---
+type: post
+title: Introduction to Brief
+---
+
+### Excerpt
+
+We're going to go over some basics about the Brief gem. This content
+won't be rendered in the final output, but will be extracted into an
+excerpt attribute for the model. 
+
+# Brief 
+## An introduction to brief
+
+This content will get rendered.
+```
+
+The Post model will turn this document into an object, and let us do 
+different things with it in our code.
+
+A post model can be used as application data in a Ruby app.
+
+```ruby
+post = Post.where(:title.matches => "Intro")
+post.title # "Introduction to Brief"
+post.status # "draft"
+```
+
+Or interacted with from the command line:
+
+```bash
+brief publish post docs/posts/introduction-to-brief.md
+```
+
+### The rest is up to you.
+
+There is more to the gem which we will cover later, but this is
+a very powerful way to build applications which are powered primarily by
+structured writing.

data/docs/markdown-extensions.md

@@ -0,0 +1,5 @@
+# Markdown Extensions
+
+Here I'll discuss some of the syntax enhancements we've made to markdown
+to make documents linkable within a briefcase, or to embed another
+documents content or embed an SVG asset inline as XML.

data/docs/views-and-commands.md

@@ -0,0 +1,3 @@
+# Views And Commands
+
+Here I'll document how the briefcase can be rendered in alternative formats using views, and how the briefcase can define commands to run on a briefcase level

data/lib/brief.rb

@@ -10,6 +10,7 @@ require 'yaml'
 require 'erb'
 require 'hike'
 require 'pry'
+require 'logger'
 
 module Brief
   # When packaging this up through the traveling ruby system

data/lib/brief/briefcase.rb

@@ -1,3 +1,14 @@
+# A Briefcase is a repository of markdown documents which are turned into active-record like model objects.
+#
+# Special behaviors can be built into these documents by assigning them a `type` value.  Doing this is done either
+# by
+#
+# A Briefcase contains a query interface for different Brief::Documents.  A Brief::Document takes YAML frontmatter,
+# and rendered markdown, and builds key / value attribute pairs for the document.  Each document expects to be able
+# to determine its type by accessing the type field contained in the YAML frontmatter
+#
+# The Briefcase allows you to treat each markdown document as
+#
 module Brief
   class Briefcase
     include Brief::DSL
@@ -9,9 +20,25 @@ module Brief
     attr_accessor :asset_finder,
                   :href_builder
 
+    # Creates a new briefcase
+    #
+    # options:
+    #   - root: (required) the root folder of the briefcase project.  will default to PWD
+    #
+    #   - app: (optional) the name of the app this briefcase should use
+    #
+    #   - logger: a logger instance, will default to Logger.new(STDOUT)
+    #
+    #   - href_builder: (optional) reference to a block which will be used to post-process any generated
+    #                   href values for the documents in this briefcase. This will generally be used by
+    #                   apps which render the briefcase content.
+    #   - asset_finder: (optional) reference to a block which will be used to find assets when used as attachments
+    #                   or when embedding inline:svg through the special image markdown syntax
     def initialize(options = {})
       @options = options.to_mash
 
+      debug "Created briefcase instance #{ object_id } at #{ root }"
+
       load_configuration
       use(:app, options[:app]) if options[:app]
 
@@ -26,15 +53,34 @@ module Brief
 
       Brief.cases[root.basename.to_s] ||= self
 
+      @logger = options.fetch(:logger, nil)
+
+      debug "Loading briefcase lib entries"
       load_briefcase_lib_entries()
     end
 
+    def logger
+      @logger ||= Logger.new(STDOUT)
+    end
+
+    def log message
+      logger.info(message)
+    end
+
+    def debug message
+      logger.debug(message) if debug?
+    end
+
+    def debug?
+      options.fetch(:debug, nil) || ENV['BRIEF_DEBUG']
+    end
+
     def load_briefcase_lib_entries
       begin
         etc = Dir[briefcase_lib_path.join("**/*.rb")]
         etc.each {|f| require(f) } if briefcase_lib_path.exist?
-      rescue
-
+      rescue => e
+        debug "Error while loading briefcase entries: #{ e.message }"
       end
     end
 

data/lib/brief/model.rb

@@ -11,11 +11,12 @@ module Brief
       include Virtus.model(finalize: false)
       include Initializers
       include AccessorMethods
+      include LoggerMethods
       include Persistence
       include Serializers
       include Reports
 
-      class_attribute :models, :after_initialization_hooks
+      class_attribute :models, :after_initialization_hooks, :logger
 
       self.models = Array(models).to_set
 
@@ -29,6 +30,20 @@ module Brief
       Brief::Model.classes << self
     end
 
+    module LoggerMethods
+      def log message
+        (!briefcase.nil? && briefcase.log(message))
+      end
+
+      def debug message
+        (!briefcase.nil? && briefcase.debug(message))
+      end
+
+      def puts message
+        (!briefcase.nil? && briefcase.log(message)) || super
+      end
+    end
+
     module AccessorMethods
       def title
         document_title

data/spec/spec_helper.rb

@@ -2,6 +2,8 @@ require 'pry'
 require 'rack/test'
 require 'brief'
 
+ENV['BRIEF_DEBUG'] = "true"
+
 Dir["#{File.dirname(__FILE__)}/support/**/*.rb"].each { |f| require f }
 
 module Brief

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: brief
 version: !ruby/object:Gem::Version
-  version: 1.17.9
+  version: 1.17.10
 platform: ruby
 authors:
 - Jonathan Soeder
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2015-07-12 00:00:00.000000000 Z
+date: 2015-07-21 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hashie
@@ -386,6 +386,20 @@ files:
 - bin/brief
 - bin/console
 - brief.gemspec
+- docs/advanced-features.md
+- docs/application-interfaces.md
+- docs/brief-apps.md
+- docs/brief-cli.md
+- docs/brief-model-classes.md
+- docs/briefcase-document-structure.md
+- docs/briefcase-folder-structure.md
+- docs/briefcase-renderers.md
+- docs/document-sections.md
+- docs/index.md
+- docs/intro.md
+- docs/markdown-extensions.md
+- docs/real-world-examples.md
+- docs/views-and-commands.md
 - examples/blog/brief.rb
 - examples/blog/docs/posts/this-is-my-first-post.md
 - lib/brief.rb