Permalink
Browse files

Documentation for Sinatra::Glorify

  • Loading branch information...
1 parent 01d4df6 commit 46406ab632aa9c9543883ee5c30e932f8bca4fc9 @zzak committed Dec 4, 2012
Showing with 142 additions and 25 deletions.
  1. +36 −21 README.md
  2. +13 −0 lib/glorify.rb
  3. +9 −0 lib/glorify/css.rb
  4. +3 −0 lib/glorify/extensions.rb
  5. +60 −0 lib/glorify/helpers.rb
  6. +2 −2 lib/glorify/renderer.rb
  7. +19 −2 lib/glorify/template.rb
View
@@ -1,4 +1,4 @@
-# glorify
+# Sinatra::Glorify
Sinatra helper to parse markdown with syntax highlighting like the pros
@@ -8,7 +8,7 @@ Renders markdown via redcarpet with syntax highlighting thanks to
Able to use fenced code blocks like github, and includes a default pygments
stylesheet.
-## install
+## Installation
```bash
gem install glorify
@@ -22,20 +22,21 @@ gem 'sinatra'
gem 'glorify'
```
-## using `Glorify::Template`
+## Sinatra::Glorify::Template
-glorify comes with a tilt template for rendering markdown.
+Sinatra::Glorify comes with a tilt template for rendering markdown.
-this allows you to override the default markdown renderer and use redcarpet2
-with pygments.rb to highlight any code blocks within your view.
+This allows you to override the default markdown renderer and use `redcarpet`
+with `pygments.rb` to highlight any code blocks within your view.
-in order to do this, you will need to prefer the template class.
+In order to do this, you will need to prefer the template class.
```ruby
Tilt.prefer Sinatra::Glorify::Template
```
-then any views that render `markdown` will use Glorify::Template instead.
+Now, any views that render via `markdown` will use Sinatra::Glorify::Template
+instead.
```ruby
register Sinatra::Glorify
@@ -44,14 +45,21 @@ get '/' do
end
```
-## using the helper
+## Sinatra::Glorify::Helpers
-if you want to stick with your current renderer and just render some code
-blocks within your view, use the `glorify` helper method.
+If you want to stick with your current renderer and just render some code
+blocks within your view, use the Sinatra::Glorify::Helpers.glorify helper
+method.
-### classical app
+Depending on the type of application you're building with Sinatra, the manner
+in which Sinatra::Glorify is used will change.
-simply `require 'glorify'` to use the helper with a classic style sinatra app.
+See the Sinatra documentation on [Modular vs. Classic
+style](http://www.sinatrarb.com/intro#Modular%20vs.%20Classic%20Style)
+
+### With a classical app
+
+Simply `require 'glorify'` to use the helper with a classic style sinatra app.
```ruby
require 'sinatra'
@@ -63,10 +71,10 @@ get '/' do
end
```
-### modular app
+### With a modular app
-you'll need to `register Sinatra::Glorify` in your sub-classed app, along with
-`require 'glorify'`, to use with a modular style sinatra app.
+You will need to `register Sinatra::Glorify` in your sub-classed app, along
+with `require 'glorify'`, to use with a modular style sinatra app.
```ruby
require 'sinatra/base'
@@ -81,9 +89,9 @@ class SubclassedApp < Sinatra::Base
end
```
-### the view
+### The view
-this is just a simple `erb` template, but you get the idea.
+This is just a simple `erb` template, but you get the idea.
```erb
<html>
@@ -96,11 +104,18 @@ this is just a simple `erb` template, but you get the idea.
</html>
```
-the default pygments stylesheet that comes with glorify is available at the
-`/pygments.css` route
+The default pygments stylesheet that comes with glorify is available at the
+`/pygments.css` route.
+
+
+## Still stuck?
+
+The Sinatra documentation on
+[extensions](http://www.sinatrarb.com/extensions.html) does a great job of
+explaining how to use and implement extensions using the Sinatra API.
-## license
+## License
```
Permission is hereby granted, free of charge, to any person obtaining a copy
View
@@ -6,8 +6,21 @@
require "glorify/template"
require "glorify/helpers"
+# Sinatra is a microframework for Ruby
+#
+# See sinatra on github for more:
+# http://github.com/sinatra/sinatra
module Sinatra
+ # Sinatra helper to parse markdown with syntax highlighting like the pros
+ #
+ # {See the README for more info}[http://github.com/zzak/glorify#readme]
module Glorify
+ # Sinatra extension setup to configure the application.
+ #
+ # Uses +settings.glorify_extensions+ for the Sinatra::Glorify::Renderer
+ #
+ # Also, registers the Sinatra::Glorify::Helpers and provides the pygments
+ # stylesheet route using Sinatra::Glorify::Helpers.glorify_css.
def self.registered(app)
app.set :glorify_extensions, Glorify::EXTENSIONS
app.helpers Glorify::Helpers
View
@@ -1,6 +1,15 @@
module Sinatra
module Glorify
module Helpers
+ # A helper route for your application to provide a pygments friendly
+ # stylesheet.
+ #
+ # Given, your Sinatra application is mounted under +/+
+ #
+ # <link rel="stylesheet" type="text/css" href="/pygments.css" />
+ #
+ # Based off {Trevor Turk's
+ # pygments/default.css}[https://github.com/trevorturk/pygments/blob/master/default.css]
def glorify_css
<<-css
.hll { background-color: #ffffcc }
@@ -1,5 +1,8 @@
module Sinatra
module Glorify
+ # Helper for Sinatra::Glorify::Renderer default options.
+ #
+ # Configure in your application through +settings.glorify_extensions+
EXTENSIONS = { :filter_html => true,
:autolink => true,
:no_intra_emphasis => true,
@@ -1,6 +1,66 @@
module Sinatra
module Glorify
+ # If you want to stick with your current renderer and just render some code
+ # blocks within your view, use the Sinatra::Glorify::Helpers.glorify helper
+ # method.
+ #
+ # Depending on the type of application you're building with Sinatra, the manner
+ # in which Sinatra::Glorify is used will change.
+ #
+ # See the Sinatra documentation on {Modular vs. Classic
+ # style}[http://www.sinatrarb.com/intro#Modular%20vs.%20Classic%20Style]
+ #
+ # === With a classical app
+ #
+ # Simply <code>require 'glorify'</code> to use the helper with a classic
+ # style sinatra app.
+ #
+ # require 'sinatra'
+ # require 'glorify'
+ # require 'erb'
+ # get '/' do
+ # @example = File.open("#{File.dirname(__FILE__)}/example.md", "rb").read
+ # erb :index
+ # end
+ #
+ # === With a modular app
+ #
+ # You will need to <code>register Sinatra::Glorify</code> in your
+ # sub-classed app, along with <code>require 'glorify'</code>, to use with a
+ # modular style sinatra app.
+ #
+ # require 'sinatra/base'
+ # require 'glorify'
+ # require 'erb'
+ # class SubclassedApp < Sinatra::Base
+ # register Sinatra::Glorify
+ # get '/' do
+ # @example = File.open("#{File.dirname(__FILE__)}/example.md", "rb").read
+ # erb :index
+ # end
+ # end
+ #
+ # === The view
+ #
+ # This is just a simple +erb+ template, but you get the idea.
+ #
+ # <html>
+ # <head>
+ # <link rel="stylesheet" type="text/css" href="/pygments.css" />
+ # </head>
+ # <body>
+ # <%= glorify @example %>
+ # </body>
+ # </html>
+ #
+ # The default pygments stylesheet that comes with glorify is available at the
+ # +/pygments.css+ route.
+ #
module Helpers
+ # Convenience method for custom markdown and templates.
+ #
+ # For modular applications you must add <code>register
+ # Sinatra::Helpers</code> to your application.
def glorify text
Redcarpet::Markdown.new(Glorify::Renderer.new,
Glorify::EXTENSIONS).render(text)
@@ -3,9 +3,9 @@
module Sinatra
module Glorify
- class Renderer < Redcarpet::Render::HTML
+ class Renderer < Redcarpet::Render::HTML # :nodoc:
- def block_code(code, lang)
+ def block_code(code, lang) # :nodoc:
Pygments.highlight(code, :lexer => lang, :options => {:encoding => "utf-8"})
end
@@ -3,14 +3,31 @@
module Sinatra
module Glorify
+ # Sinatra::Glorify comes with a tilt template for rendering markdown.
+ #
+ # This allows you to override the default markdown renderer and use
+ # +redcarpet+ with +pygments.rb+ to highlight any code blocks within your
+ # view.
+ #
+ # In order to do this, you will need to prefer the template class.
+ #
+ # Tilt.prefer Sinatra::Glorify::Template
+ #
+ # Now, any views that render via +markdown+ will use
+ # Sinatra::Glorify::Template instead.
+ #
+ # register Sinatra::Glorify
+ # get '/' do
+ # markdown :a_view_with_code_blocks
+ # end
class Template < Tilt::Template
- def prepare
+ def prepare # :nodoc:
@engine = Redcarpet::Markdown.new(Glorify::Renderer.new,
Glorify::EXTENSIONS)
@output = nil
end
- def evaluate(scope, locals, &block)
+ def evaluate(scope, locals, &block) # :nodoc:
@output ||= @engine.render(data)
end
end

0 comments on commit 46406ab

Please sign in to comment.