markdownizer 0.1.1 → 0.1.2

data/.gitignore

@@ -1,3 +1,4 @@
 pkg/*
 *.gem
 .bundle
+docs/

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    markdownizer (0.1.0)
+    markdownizer (0.1.2)
       activerecord (~> 3.0.3)
       coderay
       rdiscount
@@ -23,8 +23,14 @@ GEM
     builder (2.1.2)
     coderay (0.9.7)
     diff-lcs (1.1.2)
+    git (1.2.5)
     i18n (0.5.0)
+    mustache (0.12.0)
+    pygments (0.0.1.a)
     rdiscount (1.6.8)
+    rocco (0.5)
+      mustache
+      rdiscount
     rspec (2.4.0)
       rspec-core (~> 2.4.0)
       rspec-expectations (~> 2.4.0)
@@ -39,5 +45,11 @@ PLATFORMS
   ruby
 
 DEPENDENCIES
+  activerecord (~> 3.0.3)
+  coderay
+  git
   markdownizer!
+  pygments
+  rdiscount
+  rocco
   rspec (~> 2.4.0)

data/Rakefile

@@ -1,6 +1,60 @@
 require 'bundler'
 Bundler::GemHelper.install_tasks
 
+# Bring in Rocco tasks
+require 'rocco/tasks'
+require 'rake/clean'
+Rocco::make 'docs/', 'lib/markdownizer.rb'
+
+desc 'Build markdownizer docs'
+task :docs => :rocco
+directory 'docs/'
+
+desc 'Build docs and open in browser for the reading'
+task :read => :docs do
+  sh 'open docs/lib/rocco.html'
+end
+
+# Make index.html a copy of markdownizer.html
+file 'docs/index.html' => 'docs/lib/markdownizer.html' do |f|
+  cp 'docs/lib/markdownizer.html', 'docs/index.html', :preserve => true
+end
+task :docs => 'docs/index.html'
+CLEAN.include 'docs/index.html'
+
+# Alias for docs task
+task :doc => :docs
+
+# GITHUB PAGES ===============================================================
+
+site = 'docs'
+source_branch = 'master'
+deploy_branch = 'gh-pages'
+
+desc "generate and deploy website to github user pages"
+multitask :pages do
+  puts ">>> Deploying #{deploy_branch} branch to Github Pages <<<"
+  require 'git'
+  repo = Git.open('.')
+  puts "\n>>> Checking out #{deploy_branch} branch <<<\n"
+  repo.branch("#{deploy_branch}").checkout
+  (Dir["*"] - [site]).each { |f| rm_rf(f) }
+  Dir["#{site}/*"].each {|f| mv(f, "index.html")}
+  rm_rf(site)
+  puts "\n>>> Moving generated site files <<<\n"
+  Dir["**/*"].each {|f| repo.add(f) }
+  repo.status.deleted.each {|f, s| repo.remove(f)}
+  puts "\n>>> Commiting: Site updated at #{Time.now.utc} <<<\n"
+  message = ENV["MESSAGE"] || "Site updated at #{Time.now.utc}"
+  repo.commit(message)
+  puts "\n>>> Pushing generated site to #{deploy_branch} branch <<<\n"
+  repo.push
+  puts "\n>>> Github Pages deploy complete <<<\n"
+  repo.branch("#{source_branch}").checkout
+end
+
+# TESTS =====================================================================
+
 require 'rspec/core'
 require 'rspec/core/rake_task'
 RSpec::Core::RakeTask.new(:spec) do |spec|

data/Readme.md

@@ -4,6 +4,9 @@ A simple gem for Rails 3 to render some ActiveRecord text field as Markdown!
 
 It mixes CodeRay and RDiscount to give you awesome code highlighting :)
 
+You can check the generated Rocco documentation on the [project
+page](http://codegram.github.com/markdownizer).
+
 ##Install
 
 In your Gemfile:

data/lib/markdownizer.rb

@@ -1,3 +1,77 @@
+# **Markdownizer** is a simple solution to a simple problem.
+#
+# It is a lightweight Rails 3 gem which enhances any ActiveRecord model with a
+# singleton `markdownize!` method, which makes any text attribute renderable as
+# Markdown. It mixes CodeRay and RDiscount to give you awesome code
+# highlighting, too!
+#
+# If you have any suggestion regarding new features, Check out the [Github repo][gh],
+# fork it and submit a nice pull request :)
+#
+
+#### Install Markdownizer
+
+# Get Markdownizer in your Rails 3 app through your Gemfile:
+#
+#     gem 'markdownizer'
+#
+# If you don't use Bundler, you can alternatively install Markdownizer with
+# Rubygems:
+#
+#     gem install markdownizer
+#
+# If you want code highlighting, you should run this generator too:
+#
+#     rails generate markdownizer:install
+#
+# This will place a `markdownizer.css` file in your `public/stylesheets`
+# folder. You will have to require it manually in your layouts, or through
+# `jammit`, or whatever.
+# 
+# [gh]: http://github.com/codegram/markdownizer
+
+#### Usage
+
+# In your model, let's say, `Post`:
+#
+#     class Post < ActiveRecord::Base
+#       # In this case we want to treat :body as markdown
+#       # This will require `body` and `rendered_body` fields
+#       # to exist previously (otherwise it will raise an error).
+#       markdownize! :body
+#     end
+#
+# Then you can create a `Post` using Markdown syntax, like this:
+#
+#    Post.create body: """
+#       # My H1 title
+#       Markdown is awesome!
+#       ## Some H2 title...
+# 
+#       {% code ruby %}
+# 
+#         # All this code will be highlighted properly! :)
+#         def my_method(*my_args)
+#           something do
+#             3 + 4
+#           end
+#         end
+# 
+#       {% endcode %}
+#    """
+#
+# After that, in your view you just have to call `@post.rendered_body` and,
+# provided you included the generated css in your layout, it will display nice
+# and coloured :)
+
+#### Show me the code!
+
+# We'll need to include [RDiscount][rd]. This is the Markdown parsing library.
+# Also, [CodeRay][cr] will provide code highlighting. We require `active_record` as
+# well, since we want to extend it with our DSL.
+#
+# [rd]: http://github.com/rtomayko/rdiscount
+# [cr]: http://github.com/rubychan/coderay
 require 'rdiscount'
 require 'coderay'
 require 'active_record' unless defined?(ActiveRecord)
@@ -5,25 +79,47 @@ require 'active_record' unless defined?(ActiveRecord)
 module Markdownizer
 
   class << self
+    # Here we define two helper methods. These will be called from the model to
+    # perform the corresponding conversions and parsings.
+   
+    # `Markdownizer.markdown` method converts plain Markdown text to formatted html.
     def markdown(text)
       RDiscount.new(text).to_html
     end
 
+    # `Markdownizer.coderay` method parses a code block delimited from `{% code
+    # ruby %}` until `{% endcode %}` and replaces it with appropriate classes for
+    # code highlighting. It can take many languages aside from Ruby.
     def coderay(text)
-      text.gsub(%r[\{% highlight (\w+?) %\}(.+?)\{% endhighlight %\}]m) do
+      text.gsub(%r[\{% code (\w+?) %\}(.+?)\{% endcode %\}]m) do
         CodeRay.scan($2, $1).div(:css => :class)
       end
     end
   end
 
+  #### Public interface
+  
+  # The Markdownizer DSL is the public interface of the gem, and can be called
+  # from any ActiveRecord model.
   module DSL
+
+    # Calling `markdownize! :attribute` (where `:attribute` can be any database
+    # attribute with type `text`) will treat this field as Markdown.
     def markdownize! attribute
+      # Check that both `:attribute` and `:rendered_attribute` columns exist.
+      # If they don't, it raises an error indicating that the user should generate
+      # a migration.
       unless self.column_names.include?(attribute.to_s) &&
                self.column_names.include?("rendered_#{attribute}")
         raise "#{self.name} doesn't have required attributes :#{attribute} and :rendered_#{attribute}\nPlease generate a migration to add these attributes -- both should have type :text."
       end
+
+      # Create a `before_save` callback which will convert plain text to
+      # Markdownized html every time the model is saved.
       self.before_save :"render_#{attribute}"
 
+      # Define the converter method, which will assign the rendered html to the
+      # `:rendered_attribute` field.
       define_method :"render_#{attribute}" do
         self.send(:"rendered_#{attribute}=", Markdownizer.markdown(Markdownizer.coderay(self.send(attribute))))
       end
@@ -32,4 +128,7 @@ module Markdownizer
 
 end
 
+# Finally, make our DSL available to any class inheriting from ActiveRecord::Base.
 ActiveRecord::Base.send(:extend, Markdownizer::DSL)
+
+# And that's it!

data/lib/markdownizer/version.rb

@@ -1,3 +1,3 @@
 module Markdownizer
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

data/markdownizer.gemspec

@@ -18,6 +18,9 @@ Gem::Specification.new do |s|
   s.add_runtime_dependency 'rdiscount'
   s.add_runtime_dependency 'coderay'
 
+  s.add_development_dependency 'rocco'
+  s.add_development_dependency 'git'
+  s.add_development_dependency 'pygments'
   s.add_development_dependency 'rspec', '~> 2.4.0'
 
   s.files         = `git ls-files`.split("\n")

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 1
-  - 1
-  version: 0.1.1
+  - 2
+  version: 0.1.2
 platform: ruby
 authors: 
 - Josep M. Bach
@@ -16,7 +16,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-02-02 00:00:00 +01:00
+date: 2011-02-03 00:00:00 +01:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -61,9 +61,48 @@ dependencies:
   type: :runtime
   version_requirements: *id003
 - !ruby/object:Gem::Dependency 
-  name: rspec
+  name: rocco
   prerelease: false
   requirement: &id004 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: git
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id005
+- !ruby/object:Gem::Dependency 
+  name: pygments
+  prerelease: false
+  requirement: &id006 !ruby/object:Gem::Requirement 
+    none: false
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id006
+- !ruby/object:Gem::Dependency 
+  name: rspec
+  prerelease: false
+  requirement: &id007 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -74,7 +113,7 @@ dependencies:
         - 0
         version: 2.4.0
   type: :development
-  version_requirements: *id004
+  version_requirements: *id007
 description: Render any text as markdown, with code highlighting and all!
 email: 
 - info@codegram.com