Adding docco.

steveklabnik · steveklabnik · commit fabc277f69f1 · 2011-01-06T01:39:13.000-05:00
Doing some literate programming with Docco. Sweeet.
diff --git a/Gemfile b/Gemfile
@@ -18,6 +18,11 @@ gem "pony", "~>1.0.1"
 gem "sinatra-content-for"
 gem "exceptional"
 
+group :development do
+  gem "rocco"
+  gem "pygmentize"
+end
+
 group :test do
   gem "launchy", "~>0.3.7"
   gem "capybara", "~>0.3.9"
diff --git a/Gemfile.lock b/Gemfile.lock
@@ -42,19 +42,24 @@ GEM
       activesupport (>= 2.3.4)
       jnunemaker-validatable (~> 1.8.4)
       plucky (~> 0.3.6)
+    mustache (0.12.0)
     nokogiri (1.4.4)
     plucky (0.3.6)
       mongo (~> 1.1)
     polyglot (0.3.1)
     pony (1.0.1)
       mail (> 2.0)
+    pygmentize (0.0.2)
     rack (1.2.1)
     rack-flash (0.1.1)
       rack
     rack-test (0.5.6)
       rack (>= 1.0)
     rake (0.8.7)
     rdiscount (1.6.5)
+    rocco (0.5)
+      mustache
+      rdiscount
     rspec (2.1.0)
       rspec-core (~> 2.1.0)
       rspec-expectations (~> 2.1.0)
@@ -98,8 +103,10 @@ DEPENDENCIES
   launchy (~> 0.3.7)
   mongo_mapper (~> 0.8.4)
   pony (~> 1.0.1)
+  pygmentize
   rack-flash (~> 0.1.1)
   rdiscount (~> 1.6.5)
+  rocco
   rspec (~> 2.1.0)
   sinatra (~> 1.1)
   sinatra-content-for
diff --git a/hackety.rb b/hackety.rb
@@ -1,50 +1,128 @@
 # encoding: utf-8
 
-#first off, we need to include rubygems and sinatra
-require 'rubygems'
+# This is the source code for the [Hackety Hack website][hw]. Hackety Hack is
+# the easiest way to learn programming, and so our documentation should be
+# top-notch.
+#
+# To get started, you'll need to install some prerequisite software:
+#
+# **Ruby** is used to power the site. We're currently using ruby 1.9.2p0. I 
+# highly reccomend that you use [rvm][rvm] to install and manage your Rubies.
+# It's a fantastic tool. If you do decide to use `rvm`, you can install the 
+# appropriate Ruby and create a gemset by simply `cd`-ing into the root project
+# directory; I have a magical `.rvmrc` file that'll set you up.
+#
+# **MongoDB** is a really awesome document store. We use it to persist all of
+# the data on the website. To get MongoDB, please visit their 
+# [downloads page](http://www.mongodb.org/downloads) to find a package for your
+# system.
+#
+# After installing Ruby and MongoDB, you need to aquire all of the Ruby gems
+# that we use. This is pretty easy, since we're using **bundler**. Just do
+# this:
+#
+#     $ gem install bundler
+#     $ bundle install
+#
+# That'll set it all up! Then, you need to make sure you're running MongoDB.
+# I have to open up another tab in my terminal and type
+#
+#     $ mongod
+#
+# to get this to happen. When you're done hacking, you can hit ^-c to stop
+# `mongod` from running.
+#
+# To actually start up the site, just 
+#
+#     $ rackup
+#
+# and then visit [http://localhost:9292/](http://localhost:9292). You're good
+# to go!
+# 
+# [hw]: http://hackety-hack.com
+# [rvm]: http://rvm.beginrescueend.com/
+
+#### About hackety.rb
+#
+# This file is the main entry point to the application. It has three main
+# purposes:
+#
+# 1. Include all relevant gems and library code.
+# 2. Configure all settings based on our environment.
+# 3. Set up a few basic routes.
+#
+# Everything else is handled by code that's included from this file.
+
+#### Including gems
+
+# We need to require rubygems and bundler to get things going. Then we call
+# `Bundler.setup` to get all of the magic started.
 
-#this bundler stuff needed for heroku
+require 'rubygems'
 require 'bundler'
 Bundler.setup
 
+# We use [sinatra](http://sinatrarb.com/) for our web framework. Sinatra is
+# very light and simple. Good stuff.
 require 'sinatra'
 
-#this lets us send emails
+# [Pony](https://github.com/adamwiggins/pony) is used to send emails, just like the Pony express. Also, running `gem install pony` is really satisfying.
 require 'pony'
 
-#haml gives us all of our templates
+# [haml](http://haml-lang.com/) creates all of our templates. haml is concise
+# and expressive. I really enjoy it.
 require 'haml'
 
-#mongomapper connects us to our database
+# [MongoMapper](http://mongomapper.com/) is a library we use to make it easy to
+# store our model classes into MongoDB.
 require 'mongo_mapper'
 
-#rack-flash gives us nice flash messages
+# If you've used Rails' flash messages, you know how convenient they are.
+# rack-flash lets us use them.
 require 'rack-flash'
+use Rack::Flash
 
-#rdiscount lets us write things using markdown
+# [rdiscount](https://github.com/rtomayko/rdiscount) is a fast implementation
+# of the Markdown markup language. The web site renders most user submitted
+# comment with Markdown.
 require 'rdiscount'
 
-#we need to set up a secret to encrypt our sessions with
-use Rack::Session::Cookie, :secret => ENV['COOKIE_SECRET']
-
-#we also have to let the world know we want to use flashes
-use Rack::Flash
-
+# Rails has a `content_for` helper that lets you place different parts of your
+# view into different places in your template. This helps a lot with
+# javascript, and conditional stylesheets or other includes. It's so nice that
+# foca has written 
+# [a Sinatra version](https://github.com/foca/sinatra-content-for).
 require 'sinatra/content_for'
 
+# We moved lots of helpers into a separate file. These are all things that are
+# useful throughout the rest of the application. This file
 require_relative 'helpers'
 
+#### Configure settings
+
+# We need a secret for our sessions. This is set via an environment variable so
+# that we don't have to give it away in the source code. Heroku makes it really
+# easy to keep environment variables set up, so this ends up being pretty nice.
+use Rack::Session::Cookie, :secret => ENV['COOKIE_SECRET']
+
+# We use [Exceptional](http://www.getexceptional.com/) to keep track of errors
+# that happen. This code is from their 
+# [example documentation](http://docs.getexceptional.com/getting-started/sinatra/)
+# for Sinatra. It _might_ be better off inside of a config block, but I haven't
+# tested it in that role yet.
 if ENV['RACK_ENV'] == 'production'
   set :raise_errors, true
 
   require 'exceptional'
   use Rack::Exceptional, ENV['EXCEPTIONAL_API_KEY']
 end
 
-#this makes Haml escape any html by default. See here: http://haml-lang.com/docs/yardoc/file.HAML_REFERENCE.html#options
+# This makes [Haml escape any html](http://haml-lang.com/docs/yardoc/file.HAML_REFERENCE.html#options) by default.
 set :haml, :escape_html => true
 
-#these configure blocks only run in one environment
+# The `PONY_VIA_OPTIONS` hash is used to configure `pony`. Basically, we only
+# want to actually send mail if we're in the production environment. So we set
+# the hash to just be `{}`, except when we want to send mail.
 configure :test do
   PONY_VIA_OPTIONS = {}
 end
@@ -53,8 +131,10 @@
   PONY_VIA_OPTIONS = {}
 end
 
+# We're using [SendGrid](http://sendgrid.com/) to send our emails. It's really
+# easy; the Heroku addon sets us up with environment variables with all of the
+# configuration options that we need.
 configure :production do
-
   PONY_VIA_OPTIONS =  {
     :address        => "smtp.sendgrid.net",
     :port           => "25",
@@ -66,7 +146,11 @@
   
 end
 
-#for all environments,
+# We don't want to bother with running our own MongoDB server in production;
+# that's what The Cloud (tm) is for! So we want to double check our environment
+# variables, and if it appears that we'd like to connect to 
+# [MongoHQ](https://mongohq.com/), let's do that. Otherwise, just connect to
+# our local server running on localhost.
 configure do
   if ENV['MONGOHQ_URL']
     MongoMapper.connection = Mongo::Connection.new(ENV['MONGOHQ_HOST'], ENV['MONGOHQ_PORT'])
@@ -78,27 +162,45 @@
     MongoMapper.connection = Mongo::Connection.new('localhost')
     MongoMapper.database = "hackety-development"
   end
-  #require all of our models!
-  require_directory "models"
 end
 
+# Since Sinatra doesn't automatically load anything, we have to do it
+# ourselves. Remember that helpers.rb file? Well, we made a handy 
+# `require_directory` method that, well, `require`s a whole directory. So let's
+# include both of our models as well as our controllers.
+require_directory "models"
 require_directory "controllers"
 
+#### Set up basic routes
+
+# The first thing you'll ever see when going to the website is here. It all
+# starts with `/`. If we're logged in, we want to just redirect to the main
+# activity stream. If not, let's show that pretty splash page that sings all of
+# our praises. 
+#
+# One small note about rendering, though: Our main layout doesn't exactly work
+# for the main page, it's an exception. So we don't want to use our regular old
+# `layout.haml` file. So we tell Sinatra not to.
 get '/' do
   if logged_in?
     redirect "/stream"
   end
   haml :index, :layout => :plain
 end
 
-get '/post' do
-  haml :post
-end
-
+# Hopefully, anyone visiting the site will think that Hackety Hack sounds
+# pretty cool. If they do, they'll visit the downloads page. This'll direct
+# them to download Hackety, and sign up for an account.
+#
+# Similar to the home page, we also don't want our layout here, either.
 get '/download' do
   haml :download, :layout => :plain
 end
 
+# The main activity stream is the main page for the site when a user is logged
+# in. It lets them share what they're doing with others, and also view all of
+# the content that others have posted. So we grab it all, and sort it in the
+# opposite order that it's been updated. Wouldn't want to see old stuff!
 get '/stream' do
   @content_list = Content.all.sort{|a, b| b.updated_at <=> a.updated_at }
   haml :stream
