brief 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f22a8f02957425fed25d8adfa60cd4b9aa2ced77
-  data.tar.gz: 5c6e4bbb9a213eeaeac820cef681f17fc308d08a
+  metadata.gz: 4b51f1b01a40cf21a7cbe99d0c90bf6275ccacb3
+  data.tar.gz: df60ebe9cb374863ecd6b3c7df5f066c08e32910
 SHA512:
-  metadata.gz: 86ceea62469f2a210e595a03b056cda6297b0adbce06c90659f664b284e9d61a3b1f9be7d125ee759632bd08c8e585f2c8e3fdca74559f92675c9d56b486b067
-  data.tar.gz: 0f5fd7ccea4cd89b9243b6409297bc99525c37c2a6c5baca0f0b7aceb65f6ef067d042055f8e7915d28306c2c796f3307a35a4797c72593efedc63244af51c2c
+  metadata.gz: cef0b7d00b3c7fd405f6bcc3fce826078eb9889d18993e826844e5bfa7ed9caf26933f35fb243703eabc1958a16d398dca723682d40055d9b29e971a3e3a2486
+  data.tar.gz: 6aeb9e3cb3f3dd1bdc7ca24d4a956bd18d24ffe0bd5012bd6ad275df99d4f977dc34867b89ff420cc1d116e427859f8a01c1cc5f69c9ea2dbce6dfe8439b4c31

data/CHANGELOG.md

@@ -1,3 +1,27 @@
+### 1.0.0
+
+Rewrite.  
+
+- New style for structure definition
+
+  Instead of parsing markdown prior to rendering it in order to
+  determine the structure, I've taken a new approach where I render the markdown into HTML and then use Nokogiri.
+
+  This means I don't even really have to parse the markdown, I can just
+  let the user tell us how the documents are structured using CSS
+  selectors.
+
+  In addition to this, I've added a DSL that lets a user declare the model
+attributes.
+
+- Documents and Models
+
+  Documents are just YAML frontmatter and markdown.
+
+  Each document can be represented in model form. 
+
+  The `Brief::Model` is an ActiveModel like object.
+
 ### 1.1.0 
 
 - Introducing Briefcases
@@ -36,3 +60,49 @@
   - using a custom redcarpet markdown renderer in order to include
     data-attributes on heading tags
   - rendered html retains line number reference to the source markdown
+
+### 1.3.0
+
+- Introducing Templates
+
+  - Templates are ERB strings that can be associated with models. This
+    will convert a data structure into the appropriate markdown, so that
+    it can be persisted as a `Brief::Document` and do everything a
+    normal doc can.
+
+- Introducing Examples
+
+  - Each model class can point to an example, or include example content
+    inline as a string.
+
+- Introducing the 'write' command.
+
+  The brief CLI will have a write command for each model, which 
+  will open up $EDITOR and load the example content for a model
+
+  so for example, given a model:
+
+  ```
+  define "User Story" do
+
+  example <<- EOF
+  ---
+  type: user_story
+  status: draft
+  ---
+
+  # User story example
+  
+  As a **user** I would like to **do this thing** so that I can
+  **achieve this goal**
+  EOF
+  end
+  ```
+
+  When I run this on the command line:
+
+  ```bash
+  brief write user story
+  ```
+
+  then it will open up $EDITOR

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    brief (1.2.0)
+    brief (1.3.0)
       activemodel
       activesupport
       commander
@@ -55,7 +55,7 @@ GEM
     mini_portile (0.6.2)
     minitest (5.5.1)
     multipart-post (2.0.0)
-    nokogiri (1.6.5)
+    nokogiri (1.6.6.2)
       mini_portile (~> 0.6.0)
     octokit (3.7.0)
       sawyer (~> 0.6.0, >= 0.5.3)

data/README.md

@@ -1,120 +1,193 @@
 # Brief 
 
-An ActiveRecord style layer on top of a folder of markdown files.
+Brief is a tool for building applications on top of collections of
+documents written in markdown.  
 
-Treat your markdown documents as active models, run actions on them,
-convert them into HTML, extract fragments of HTML, combine it all in
-whatever interesting way you can think of.  
+Brief lets you define models very similar to how you would in
+ActiveRecord and Rails, but instead of rows in a database you are 
+going to be working with files in a folder.
 
-The end result is a really neat way of being able to use the words that you write
-to power all sorts of applications. 
+### Getting Started
+```
+gem install brief
+brief --help
+```
+
+### Hypothetical Example
+
+```
+brief init my-cookbook
+cd my-cookbook
+brief generate model Recipe # View the DOCUMENTATION for what you can do with a model
+brief write recipe # => opens up your $EDITOR with an example recipe
+```
+
+Brief treats each markdown file as an active record style model object. It treats a folder of markdown files like a database.
+
+### How does it work?
+
+Brief takes a markdown file which looks like:
+
+```markdown
+---
+type: post
+status: active
+---
+
+# An introduction to brief 
+## Stop writing dead documents 
+
+Brief is a tool which lets you define different patterns of markdown
+headings (h1,h2,h3 etc). This lets you work with collections of your
+writings, and treat each document as a database. 
+```
+
+And turns it into data, not only using the metadata up top, but also the information
+contained in the structure of the document itself.  The headings, subheadings, pretty much
+anything you could query from the HTML using CSS can be turned into key value pairs that you can work
+with and build applications on top of.
+
+With your enhanced writing, you can do things like:
+
+```ruby
+# Find all the posts which are active:
+posts = briefcase.posts.where(status:"published")
+
+# Get their titles, and subheadings:
+posts.map(&:title) #=>['An introduction to brief']
+posts.map(&:subheading) #=>['Stop writing dead documents']
 
-**No more writing dead documents!**
+# Publish the post
+posts.first.publish()
 
-### Documents as Models
+# Email the drafts to your editor
+posts.where(status:"draft").each &:mail_to_editors
+```
 
-Brief lets you treat an individual markdown file as if it were a model,
-complete with validations, callbacks, and methods you can run. You can
-define a `Post` model for all of the files in a 'posts' folder and
-define actions like 'publish' on them. 
+From the Command line we can:
+
+```bash
+brief publish posts 
+brief write post #=> Opens your editor
+```
+
+This type of interactivity is made possible by the `Brief::Model`
+
+### Documents as models
 
 ```ruby
 define "Post" do
   meta do
     status
-    tags Array
   end
 
   content do
-    has_one :title, "h1"
-    has_many :subheadings, "h2"
+    title "h1:first-of-type"
+    subheading "h2:first-of-type"
+    sample "p:first-of-type"
   end
 
   actions do
     def publish
-      update_attributes(:status => "published")
+      update_attributes(status: "published")
     end
   end
 end
 ```
 
+### CLI Tool
 
-### Model attributes derived from YAML frontmatter 
+Brief gives you a CLI called `brief`
 
-Models can get their attributes from headers on the document, aka YAML frontmatter.
-
-```markdown
----
-status: draft
-tags: 
-  - demo
-  - sample
----
+This lets you run some general commands, but also gives you an
+intelligent interface to work with your models.  In the above example,
+we defined some actions.
 
-# Title
+This will be available in the CLI:
 
-## Section One
-## Section Two
 ```
-
-which will let you use it like such:
-
-```ruby
-post = Brief::Document.new(/path/to/doc.html.md)
-
-post.status #=> "draft"
-post.title #=> "Title"
-post.tags #=> ['demo','sample']
+brief publish posts ./docs/posts/*.md
 ```
 
-#### Model attributes derived from the document structure
-
-Models can also get their attributes from the structure itself.
+This will find all of the matching documents, turn them into `Post`
+models, and then run the publish method on them.  You can make your
+models as advanced as you want:
 
-```ruby
-post.title #=> "Title"
-post.subheadings #=> ["Section One", "Section Two"]
+```
+define "Post" do
+  actions do
+    def submit 
+      update_attributes(status:"submitted to editors")
+      mailer.send(:to => "jon@chicago.com", :subject => "Please review: #{ self.title }")
+    end
+  end
+end
 ```
 
-### Querying Documents
-
-Given a big folder of markdown files with attributes, we can query them:
+### YAML Frontmatter
 
-```
-posts = briefcase.posts.where(:status => "published")
-posts.map(&:title) #=> ['Title']
-```
+Each markdown document can contain YAML frontmatter.  This data will be
+available and associated with each document or model, and will also let
+you query, filter, and sort your documents.
 
-This functionality is based on https://github.com/ralph/document_mapper,
-and similar to middleman.
+### CSS Structure Definition
 
-### Document Actions
+Since markdown renders into HTML, and HTML Documents can be queried
+using CSS selectors, we use CSS selectors in our model definition DSL so
+that we can isolate certain parts of the document, and use the content
+it contains as metadata.
 
-By defining actions on documents like so:
+A real world example:
 
 ```ruby
-
-define "Post" do
-  actions do
-    def publish
-      # DO Something
+  content do
+    title "h1:first-of-type"
+    define_section "User Stories" do
+      each("h2").has(:title     => "h2",
+                     :paragraph => "p:first-of-type",
+                     :components   => "p:first-of-type strong"
+                    )
+
+      each("h2").is_a :user_story
     end
   end
-end
 ```
 
-you can either call that method as you normally would: 
+This lets me turn a markdown file like:
 
-```ruby
-post = Brief.case.posts.where(:status => "draft")
-post.publish()
+```markdown
+---
+title: Epic Example
+status: published
+---
+# Epic Example
+# User Stories
+
+## A user wants to do something
+As a **User** I would like to **Do this** so that I can **succeed**
+
+## A user wants to do something else
+As a **User** I would like to **Do this** so that I can **succeed**
 ```
 
-or you can run that action from the command line:
+into:
 
-```bash
-brief publish posts ./posts/*.html.md
+```ruby
+{
+  title: "Epic Example",
+  status: "published",
+  type: "epic",
+  user_stories:[{
+    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",
+    persona: "user",
+    behavior: "do something"
+  },{
+    title: "A user wants to do something else",
+    paragraph: "As a user I would like to do something else so that I can succeed"
+  }]
+}
 ```
 
-this will find all of the post models matching the document, and then
-call the publish method on them.
+And we can even go in the other direction.

data/lib/brief/adapters/middleman.rb

@@ -1,16 +1,15 @@
 module Brief::Adapters
   class MiddlemanExtension
-
     def self.activate_brief_extension
       ::Middleman::Extensions.register(:brief, Brief::Adapters::MiddlemanExtension)
     end
 
-    def initialize(app, options_hash={}, &block)
+    def initialize(app, options_hash = {}, &block)
       super
 
       app.include(ClassMethods)
 
-      options_hash.each do |key,value|
+      options_hash.each do |key, value|
         app.set(key, value)
       end
     end

data/lib/brief/briefcase.rb

@@ -5,7 +5,7 @@ module Brief
     attr_reader :options,
                 :model_definitions
 
-    def initialize(options={})
+    def initialize(options = {})
       @options = options.to_mash
 
       load_configuration
@@ -16,6 +16,16 @@ module Brief
       end
     end
 
+    def use(module_type=:app, module_id)
+      if module_type == :app && apps_path.join(module_id).exist?
+        config = module_type.join("config.rb")
+        models = module_type.join("models")
+
+        instance_eval(config.read) if config.exist?
+        Brief.load_modules_from(models) if models.exist?
+      end
+    end
+
     def config
       Brief::Configuration.instance
     end
@@ -24,19 +34,32 @@ module Brief
     # or the configured path for the configuration file.
     def load_configuration
       config_path = options.fetch(:config_path) do
-        root.join("brief.rb")
+        root.join('brief.rb')
+      end
+
+      if uses_app?
+        instance_eval(app_path.join("config.rb").read)
       end
 
       if config_path.exist?
-        instance_eval(config_path.read)
+        instance_eval(config_path.read) rescue nil
       end
     end
 
+    def uses_app?
+      options.key?(:app) && Brief.apps_path.join(options[:app]).exist?
+    end
+
+    def app_path
+      uses_app? && Brief.apps_path.join(options[:app])
+    end
+
     def load_model_definitions
-      if models_path.exist?
-        Dir[models_path.join("**/*.rb")].each {|f| require(f) }
+      if uses_app?
+        Brief.load_modules_from(app_path.join("models"))
       end
 
+      Brief.load_modules_from(models_path) if models_path.exist?
       Brief::Model.finalize
     end
 

data/lib/brief/cli/change.rb

@@ -1,11 +1,11 @@
-command "change" do |c|
-  c.syntax = "brief change ATTRIBUTE [OPTIONS]"
-  c.description = "change attributes of brief documents"
+command 'change' do |c|
+  c.syntax = 'brief change ATTRIBUTE [OPTIONS]'
+  c.description = 'change attributes of brief documents'
 
-  c.option "--from", String, "Only apply when the attributes current value matches."
-  c.option "--to", String, "Only apply when the attributes current value matches."
-  c.option "--files", String, "The files you want to change"
-  c.option "--on", String, "alias for --files. The files you want to change"
+  c.option '--from', String, 'Only apply when the attributes current value matches.'
+  c.option '--to', String, 'Only apply when the attributes current value matches.'
+  c.option '--files', String, 'The files you want to change'
+  c.option '--on', String, 'alias for --files. The files you want to change'
 
   c.action do |args, options|
     puts "Args: #{ args.inspect }"

data/lib/brief/cli/init.rb

@@ -1,27 +1,26 @@
-command "init" do |c|
-  c.syntax = "brief init NAME [OPTIONS]"
-  c.description = "Create a new brief project, aka a briefcase"
+command 'init' do |c|
+  c.syntax = 'brief init NAME [OPTIONS]'
+  c.description = 'Create a new brief project, aka a briefcase'
 
-  c.option "--root", String, "The root folder for the new project."
+  c.option '--root', String, 'The root folder for the new project.'
 
   c.action do |args, options|
-    options.default(:root => Dir.pwd())
+    options.default(root: Dir.pwd)
 
     if path = args.first
       root = Pathname(options.root).join(path)
     end
 
-    [root, root.join("models"), root.join("docs")].each do |p|
+    [root, root.join('models'), root.join('docs')].each do |p|
       puts "== folder #{ p.basename } #{ '. exists' if p.exist? }"
       FileUtils.mkdir_p(p) unless p.exist?
     end
 
-
-    if root.join("brief.rb").exist?
-      say "== Briefcase config already exists. Skipping."
+    if root.join('brief.rb').exist?
+      say '== Briefcase config already exists. Skipping.'
     else
-      say "== Creating config file brief.rb"
-      root.join("brief.rb").open("w+") do |fh|
+      say '== Creating config file brief.rb'
+      root.join('brief.rb').open('w+') do |fh|
         default_config = <<-EOF
 
 config do

data/lib/brief/cli/write.rb

@@ -0,0 +1,23 @@
+command 'write' do |c|
+  c.syntax = 'brief write MODEL_TYPE [OPTIONS]'
+  c.description = 'Create a new document for a given model type'
+
+  c.action do |args, _options|
+    string_args = args.select { |a| a.is_a?(String) }
+    model_class = Brief::Model.lookup_class_from_args(string_args)
+
+    base_content = ''
+
+    if model_class && model_class.example_body.to_s.length > 0
+      base_content = model_class.example_body
+    else
+      # document_contents = model_class.inspect + model_class.example_body.to_s
+    end
+
+    document_contents = ask_editor(base_content)
+    file = ask('enter a name for this file:', String)
+
+    puts file
+    puts document_contents
+  end
+end

data/lib/brief/configuration.rb

@@ -14,12 +14,12 @@ module Brief
 
     def current
       @current ||= {
-        docs_path: "docs",
-        models_path: "models"
+        docs_path: 'docs',
+        models_path: 'models'
       }.to_mash
     end
 
-    def set(attribute, value=nil)
+    def set(attribute, value = nil)
       current[attribute] = value
       self
     end
@@ -33,6 +33,5 @@ module Brief
         nil
       end
     end
-
   end
 end

data/lib/brief/document/content_extractor.rb

@@ -5,9 +5,7 @@ module Brief
       @document = document
     end
 
-    def document
-      @document
-    end
+    attr_reader :document
 
     def model_class
       Brief::Model.for_type(@model_type)
@@ -21,7 +19,7 @@ module Brief
       attribute_set.key?(meth) || super
     end
 
-    def method_missing(meth, *args, &block)
+    def method_missing(meth, *_args, &_block)
       if settings = attribute_set.fetch(meth, nil)
         if settings.args.length == 1 && settings.args.first.is_a?(String)
           selector = settings.args.first

data/lib/brief/document/front_matter.rb

@@ -15,10 +15,10 @@ module Brief
 
       def load_frontmatter
         if raw_content =~ /^(---\s*\n.*?\n?)^(---\s*$\n?)/m
-          self.content = raw_content[($1.size + $2.size)..-1]
-          @frontmatter_line_count = $1.lines.size
-          @raw_frontmatter = $1
-          @frontmatter = YAML.load($1).to_mash
+          self.content = raw_content[(Regexp.last_match[1].size + Regexp.last_match[2].size)..-1]
+          @frontmatter_line_count = Regexp.last_match[1].lines.size
+          @raw_frontmatter = Regexp.last_match[1]
+          @frontmatter = YAML.load(Regexp.last_match[1]).to_mash
         end
       end
     end

data/lib/brief/document/rendering.rb

@@ -19,11 +19,11 @@ module Brief
 
         def renderer
           @renderer ||= begin
-                          r = renderer_class.new(:tables => true,
-                                            :autolink => true,
-                                            :gh_blockcode => true,
-                                            :fenced_code_blocks => true,
-                                            :footnotes => true)
+                          r = renderer_class.new(tables: true,
+                                                 autolink: true,
+                                                 gh_blockcode: true,
+                                                 fenced_code_blocks: true,
+                                                 footnotes: true)
 
                           ::Redcarpet::Markdown.new(r)
                         end
@@ -36,7 +36,7 @@ module Brief
       # which allows us to wrap things in section containers, apply data
       # attributes, and other things to the HTML so that the output HTML retains its
       # relationship to the underlying data and document structure.
-      def to_html(options={})
+      def to_html(options = {})
         if options[:wrap] == false
           unwrapped_html
         else
@@ -59,9 +59,7 @@ module Brief
         @renderer ||= self.class.renderer
       end
 
-      def renderer=(value)
-        @renderer = value
-      end
+      attr_writer :renderer
     end
   end
 end