From 38d519bf8fb6a54e5b5da30287c83a1932315724 Mon Sep 17 00:00:00 2001 From: Dave Perrett Date: Sat, 21 May 2011 17:54:20 +1000 Subject: [PATCH] Converted README to markdown. --- README.textile => README.markdown | 177 ++++++++++++++++-------------- 1 file changed, 97 insertions(+), 80 deletions(-) rename README.textile => README.markdown (53%) diff --git a/README.textile b/README.markdown similarity index 53% rename from README.textile rename to README.markdown index 9e58c92..a00982d 100644 --- a/README.textile +++ b/README.markdown @@ -1,107 +1,115 @@ -h2. About +About +----- I needed a solid base to build my own rails projects from. Since integrating all these disparate pieces isn't the easiest thing in the world, I decided to release this sample site in the hope that it would save you some time as well. The demo application is designed to provide a solid, generic skeleton to base your next rails project on, and includes everything you'll need to dive straight in and get started. -h2. Demo Site +Demo Site +--------- -You can try out a live demo of the project at "railskitchensink.com":http://railskitchensink.com/. The database will be automatically re-generated every hour, so don't be surprised if any changes disappear. +You can try out a live demo of the project at [railskitchensink.com](http://railskitchensink.com/). The database will be automatically re-generated every hour, so don't be surprised if any changes disappear. -h2. License +License +------- -This project is distributed under the "MIT License":http://en.wikipedia.org/wiki/MIT_license. See the "License":https://github.com/recurser/rails-kitchen-sink/blob/master/LICENSE file for details. +This project is distributed under the [MIT License](http://en.wikipedia.org/wiki/MIT_license). See the [License](https://github.com/recurser/rails-kitchen-sink/blob/master/LICENSE) file for details. -h2. Installation +Installation +------------ To get started, first download the source via git -{% highlight bash %} -$ git clone git://recursive-design.com/rails-kitchen-sink.git -$ cd rails-kitchen-sink -{% endhighlight %} +```bash +> git clone git://recursive-design.com/rails-kitchen-sink.git +> cd rails-kitchen-sink +``` Next, install the requisite gems: -{% highlight bash %} -$ gem install bundler -$ bundle install -{% endhighlight %} +```bash +> gem install bundler +> bundle install +``` Set up the database: -{% highlight bash %} -$ rake db:setup -{% endhighlight %} +```bash +> rake db:setup +``` Finally, run the local development server to try it out: -{% highlight bash %} -$ rails s -{% endhighlight %} +```bash +> rails s +``` -The demo application should now be available at "http://localhost:3000/":http://localhost:3000/. +The demo application should now be available at [http://localhost:3000/](http://localhost:3000/). -h2. What's Included? +What's Included? +---------------- I've tried to create a sensible base to start build your Rails 3 applications off of, with all the packages I generally use pre-integrated. _Rails Kitchen Sink_ currently combines: -* "Devise":http://github.com/plataformatec/devise authentication. -* "CanCan":http://github.com/ryanb/cancan authorization. -* "HAML":http://haml-lang.com/ templates. -* "CoffeeScript":http://jashkenas.github.com/coffee-script/ support. -* "metric_fu":http://metric-fu.rubyforge.org/ reports. -* Full "RSpec":http://rspec.info/ test suite. -* "Spork":http://github.com/timcharper/spork DRb server. -* "960":http://960.gs/ CSS grid system. -* "Jammit":http://documentcloud.github.com/jammit/ asset packaging. -* "Formtastic":http://github.com/justinfrench/formtastic forms. +* [Devise](http://github.com/plataformatec/devise) authentication. +* [CanCan](http://github.com/ryanb/cancan) authorization. +* [HAML](http://haml-lang.com/) templates. +* [CoffeeScript](http://jashkenas.github.com/coffee-script/) support. +* [metric_fu](http://metric-fu.rubyforge.org/) reports. +* Full [RSpec](http://rspec.info/) test suite. +* [Spork](http://github.com/timcharper/spork) DRb server. +* [960](http://960.gs/) CSS grid system. +* [Jammit](http://documentcloud.github.com/jammit/) asset packaging. +* [Formtastic](http://github.com/justinfrench/formtastic) forms. -h2. Testing -_Rails Kitchen Sink_ comes pre-configured for "Spork":http://github.com/timcharper/spork and "autotest":http://www.zenspider.com/ZSS/Products/ZenTest/#rsn support. I generally work by running _spork_ in one terminal: +Testing +------- -{% highlight bash %} -$ cd rails-kitchen-sink -$ spork +_Rails Kitchen Sink_ comes pre-configured for [Spork](http://github.com/timcharper/spork) and [autotest](http://www.zenspider.com/ZSS/Products/ZenTest/#rsn) support. I generally work by running _spork_ in one terminal: + +```bash +> cd rails-kitchen-sink +> spork Using RSpec Loading Spork.prefork block... Spork is ready and listening on 8989! -{% endhighlight %} +``` ... and running _autotest_ in another: -{% highlight bash %} -$ cd rails-kitchen-sink -$ autotest +```bash +> cd rails-kitchen-sink +> autotest ........................................................................................ Finished in 29.27 seconds 88 examples, 0 failures -{% endhighlight %} +``` -Autotest will run the test suite automatically whenever you save changes, and if you're working on OSX, it will provide "Growl":http://growl.info/ feedback every time the test suite is run: +Autotest will run the test suite automatically whenever you save changes, and if you're working on OSX, it will provide [Growl](http://growl.info/) feedback every time the test suite is run: !http://recursive-design.com/images/projects/rails-kitchen-sink/autotest_growl_notification.png! -h2. Deploying To Heroku +Deploying To Heroku +------------------- -To deploy the application to "Heroku":http://heroku.com/, simply run _heroku create_: +To deploy the application to [Heroku](http://heroku.com/,) simply run _heroku create_: -{% highlight bash %} -$ heroku create +```bash +> heroku create Creating evening-beach-14... done Created http://evening-beach-14.heroku.com/ | git@heroku.com:evening-beach-14.git Git remote heroku added -{% endhighlight %} +``` The _evening-beach-14_ part will vary depending on the name Heroku chooses for your application. To push your newly created application to Heroku, do a _git push heroku master_: -{% highlight bash %} -$ git push heroku master +```bash +> git push heroku master Counting objects: 1669, done. Delta compression using up to 4 threads. Compressing objects: 100% (629/629), done. @@ -127,31 +135,32 @@ Total 1669 (delta 955), reused 1657 (delta 949) To git@heroku.com:evening-beach-14.git * [new branch] master -> master -{% endhighlight %} +``` Next, create the database on Heroku: -{% highlight bash %} -$ heroku rake db:setup -{% endhighlight %} +```bash +> heroku rake db:setup +``` -You should also install the free "SendGrid":http://sendgrid.com/ add-on for email delivery: +You should also install the free [SendGrid](http://sendgrid.com/) add-on for email delivery: -{% highlight bash %} -$ heroku addons:add sendgrid:free -{% endhighlight %} +```bash +> heroku addons:add sendgrid:free +``` -Your application should now be available at "http://evening-beach-14.heroku.com/":http://evening-beach-14.heroku.com/ (substitute the domain you received from _git push heroku_ here). +Your application should now be available at [http://evening-beach-14.heroku.com/](http://evening-beach-14.heroku.com/) (substitute the domain you received from _git push heroku_ here). Whenever you push changes to git, you can update heroku by doing _git push heroku_ again. -h2. Git hooks +Git hooks +--------- CoffeeScript and Compass both require generated files to be saved when they're compiled - this causes a problem on Heroku because access to the filesystem is limited. There are various hacks to get around this by saving to the _tmp_ folder and re-routing requests, but I decided it was probably easiest to just add the generated files to git and deploy them normally. To achieve this, I added a post-commit hook to the repository to generate these files whenever changes are committed. To add these, create the file _.git/hooks/pre-commit_ , make it executable, and add the following contents: -{% highlight bash %} +```bash #!/bin/sh compass compile @@ -159,57 +168,65 @@ rake public/javascripts/application.js jammit git add public/assets/common* git add public/javascripts/application.js -{% endhighlight %} +``` The first two commands generate the CSS and Javascript respectively, the 3rd command packages them up using Jammit, and the last two make sure they are included in the commit. -h2. Internationalization +Internationalization +-------------------- -_Rails Kitchen Sink_ is fully I18N-ready, but unfortunately the only translation is currently (i assume fairly badly) auto-generated-french from Google translate. If you'd like to contribute a translation, you can start by looking at the "translation files":https://github.com/recurser/rails-kitchen-sink/tree/master/config/locales and "static pages":https://github.com/recurser/rails-kitchen-sink/tree/master/app/views/pages. There's not a great deal of text to translate, so if anyone is feeling particularly generous and/or bored, additional translations would be very much appreciated! +_Rails Kitchen Sink_ is fully I18N-ready, but unfortunately the only translation is currently (i assume fairly badly) auto-generated-french from Google translate. If you'd like to contribute a translation, you can start by looking at the [translation files](https://github.com/recurser/rails-kitchen-sink/tree/master/config/locales) and [static pages](https://github.com/recurser/rails-kitchen-sink/tree/master/app/views/pages). There's not a great deal of text to translate, so if anyone is feeling particularly generous and/or bored, additional translations would be very much appreciated! -h2. Stylesheets +Stylesheets +----------- Stylesheets in the _public/stylesheets_ folder are automatically generated by compass, so any changes you make to these files will be lost. Instead, you should edit the _sass_ files in _app/stylesheets_. When altering stylesheets during development, you should run _compass watch_ to make sure your changes are automatically compiled to _public/stylesheets_: -{% highlight bash %} -$ compass watch +```bash +> compass watch >>> Compass is watching for changes. Press Ctrl-C to Stop. -{% endhighlight %} +``` -h2. Javascript +Javascript +---------- Similarly, _public/javascripts/application.js_ is automatically generated by the CoffeeScript compiler. Instead of editing it directly, edit _application/scripts/application.coffee_ instead. Unlike Compass, there is no need to run a _watch_ script for this file during development - it will automatically be compiled for you. -h2. Asset Packaging +Asset Packaging +--------------- -JavaScript and CSS are automatically compressed and packaged for production with "Jammit":http://documentcloud.github.com/jammit/. During development, the non-compressed versions will be served to speed things up. This packaging should be fairly transparent to you if you set up the git pre-commit hook described above - if you choose not to do this you will need to run the _jammit_ command manually before committing changes. +JavaScript and CSS are automatically compressed and packaged for production with [Jammit](http://documentcloud.github.com/jammit/). During development, the non-compressed versions will be served to speed things up. This packaging should be fairly transparent to you if you set up the git pre-commit hook described above - if you choose not to do this you will need to run the _jammit_ command manually before committing changes. -h2. Bug Reports +Bug Reports +----------- -If you come across any problems, please "create a ticket":https://github.com/recurser/rails-kitchen-sink/issues and we'll try to get it fixed as soon as possible. +If you come across any problems, please [create a ticket](https://github.com/recurser/rails-kitchen-sink/issues) and we'll try to get it fixed as soon as possible. -h2. Contributing +Contributing +------------ Once you've made your commits: -1. "Fork":http://help.github.com/fork-a-repo/ rails-kitchen-sink +1. [Fork](http://help.github.com/fork-a-repo/) rails-kitchen-sink 2. Create a topic branch - `git checkout -b my_branch` 3. Push to your branch - `git push origin my_branch` -4. Create a "Pull Request":http://help.github.com/pull-requests/ from your branch +4. Create a [Pull Request](http://help.github.com/pull-requests/) from your branch 5. That's it! -h2. Author +Author +------ -Dave Perrett :: mail@recursive-design.com :: "@recurser":http://twitter.com/recurser +Dave Perrett :: mail@recursive-design.com :: [@recurser](http://twitter.com/recurser -h2. Copyright +Copyright +--------- -Copyright (c) 2010 Dave Perrett. See "License":https://github.com/recurser/rails-kitchen-sink/blob/master/LICENSE for details. +Copyright) (c) 2010 Dave Perrett. See [License](https://github.com/recurser/rails-kitchen-sink/blob/master/LICENSE) for details.