chriseppstein/compass — pull request #1070 by silvenon (2012-10-31 02:34:21+00:00)
Title: Improve documentation editing environment

These changes were really connected so I found it hard to keep them in seperate commits, sorry :P

@chriseppstein told me that the documentation contributing workflow is supposed to be easy even for non-rubyists, but they were pretty messy. I'm not a rubyist so my changes didn't make the compilation process much faster, but I believe they made it easier.

I updated the gems, some of them were really old, most notably **nanoc**. After updating it I fixed some syntax deprecation warnings, updated the data sources and fixed an error I wanted to ask about. There are two lines in `lib/examples.rb` which were raising an error:

```rb
markup_item.reps.find { |r| r.name == :default }.content_at_snapshot(:raw)
# ...
markup_item.reps.find { |r| r.name == :default }.content_at_snapshot(:raw)
```
The error said that `:raw` snapshot doesn't exist for those items. I'm not so awesome with nanoc, but changing `:raw` to `:last` seemed to fix it. I just wanted someone to correct me if I did something wrong here.

Now, for the compilation process. I removed the binstubs practice because it's kind of weird, I don't see how `./bin/something` is better from `bundle exec something`. Moreover, nanoc uses Gemfile by default, so no `bundle exec` is needed :)

Also, I made the `nanoc aco` approach secondary, as it's sluggish and ineffective (or there's something magical about it that I didin't realize). The primary approac is now `nanoc watch`+`nanoc view`, combined in a Procfile, which can be run with Foreman. Running `process1 & process2` is cool until you have to stop `process1`. Now the site can be previewed and compiled by simply running:
```
$ foreman start
```
Port 3000, same as it was before.

I removed the Serve bit completely. Maybe that was stupid, but I didn't understand it at all, it seemed like running Serve just ran nanoc in some way, but I don't know how. I think that the current `nanoc watch`+`nanoc view` approach kinda does what `serve`+`rake watch` did, right? Can someone explain?

Lastly, I made README totally user-friendly, I hope you'll be happy with it ;)