Permalink
Browse files

Migrated existing README's from sinatra_more over to padrino gems

  • Loading branch information...
1 parent f0beeb0 commit 0b6a6019658d98a49397746b5811272bdc506b76 @nesquena nesquena committed Nov 18, 2009
Showing with 613 additions and 5 deletions.
  1. +67 −1 README.rdoc
  2. +55 −1 padrino-gen/README.rdoc
  3. +340 −1 padrino-helpers/README.rdoc
  4. +76 −1 padrino-mailer/README.rdoc
  5. +75 −1 padrino-routing/README.rdoc
View
@@ -2,4 +2,70 @@
Padrino is the godfather of Sinatra.
-More info coming soon
+== Preface
+
+This gem has been designed to work on top of and enhance Sinatra (http://www.sinatrarb.com).
+Sinatra is a DSL for quickly creating web applications in Ruby with minimal effort.
+The canonical example of how to create an entire simple web application with Sinatra is something like:
+
+ # myapp.rb
+ require 'rubygems'
+ require 'sinatra'
+ get '/' do
+ 'Hello world!'
+ end
+
+and then to run the application:
+
+ $ ruby myapp.rb
+
+The extreme simplicity of the framework is quite refreshing. We have been using Sinatra a great deal
+for recent projects. First for small and simple json and xml web services and then even
+for more complex full-featured applications. This gem represents an attempt to make it as fun and easy
+as possible to code increasingly advanced view-heavy web applications in Sinatra.
+
+== Introduction
+
+Note: This library is still experimental and may not be ready for production just yet.
+That being said the gem is being actively used on a number of sinatra projects.
+In addition, the gem has fairly solid test coverage ensuring that everything works as expected.
+
+This will be a framework which expands sinatra's capabilities in a variety of ways.
+Note that all extensions have been created to work with haml, erb, and erubis.
+This gem is intended to be template-agnostic in providing helpers wherever possible.
+
+Let me expand briefly on what I want to accomplish with this gem. I love sinatra but if I want to use it
+for any non-trivial application I very quickly miss a lot of the extra tools provided by rails.
+
+Now the obvious question is "Why not just use rails then?" Well, in many cases that might be the right decision.
+Still, at least until version 3 comes along, Rails is quite a large framework with a 'take it or leave it' attitude.
+Personally, I have come to love the spirit of sinatra which acts as a thin wrapper on top of rack
+often allowing middleware to do most of the work and pulling in additional complexity only as required.
+
+My goal with this extension is to match the spirit of Sinatra and at the same time create a standard library
+of tools, helpers and components that will make Sinatra suitable for more complex applications.
+
+Here is a small list of what Padrino contains:
+
+* Code generators for creating new padrino applications (using <tt>padrino_gen</tt> on command line)
+* Generic view and tag helpers (<tt>tag</tt>, <tt>content_tag</tt>, <tt>input_tag</tt>, ...)
+* Asset tag helpers (<tt>link_to</tt>, <tt>image_tag</tt>, <tt>javascript_include_tag</tt>, ...)
+* Full form helpers and builders support (<tt>form_tag</tt>, <tt>form_for</tt>, <tt>field_set_tag</tt>, <tt>text_field</tt>, ...)
+* Full url named route support to avoid hardcoding route url paths (<tt>map</tt>, <tt>url_for</tt>)
+* Generally useful formatting extensions (<tt>relative_time_ago</tt>, <tt>js_escape_html</tt>, <tt>sanitize_html</tt>)
+* Simple 'mailer' email delivery support (akin to <tt>ActionMailer</tt> but simpler)
+* Automatic authentication and administrative views out of the box
+
+Keep in mind, the user will be able to pull in these components seperately and leave out those that are not required
+or use them altogether for a comprehensive upgrade to Sinatra (a full-stack Padrino application).
+
+Please help me brainstorm and fork the project if you have any ideas to contribute.
+
+== Installation
+
+To install the padrino framework, simply grab the latest version from gemcutter:
+
+ $ sudo gem install padrino --source http://gemcutter.org
+
+This will install the necessary padrino gems to get you started.
+Now you are ready to use this gem in your sinatra project or to create Padrino applications.
@@ -1,6 +1,60 @@
= padrino-gen
-Description goes here.
+In addition to the support provided above, padrino also comes preloaded with flexible code generators for Sinatra
+powered in part by the excellent Thor gem (incidentally also used in the Rails 3 generators). These generators are intended
+to allow for easy code generation both in creating new applications and building on existing ones. The generators have been
+built to be as library-agnostic as possible, supporting a myriad of test frameworks, js libraries, mocking libraries, etc.
+
+The usage for the generator is quite simple:
+
+ $ padrino-gen <the_app_name> </path/to/create/app> --<component-name> <value>
+
+The simplest possible command to generate a base application would be:
+
+ $ padrino-gen demo_app .
+
+This would construct a Sinatra application DemoApp (which extends from Sinatra::Application)
+inside the folder 'demo_app' at our current path. Inside the application there would be configuration and
+setup performed for the default components.
+
+You can also define specific components to be used:
+
+ $ padrino-gen demo_app . --test=rspec --renderer=haml --mock=rr --script=jquery --orm datamapper
+
+There is also support for aliases for each component within the command:
+
+ $ padrino-gen demo_app . -t=rspec -r=haml -m=rr -s=jquery -d=datamapper
+
+The available components and their default options are listed below:
+
+* test: <tt>bacon</tt> (default), <tt>shoulda</tt>, <tt>rspec</tt>, <tt>testspec</tt>, <tt>riot</tt>
+* renderer: <tt>erb</tt> (default), <tt>haml</tt>
+* mock: <tt>mocha</tt> (default), <tt>rr</tt>
+* script: <tt>jquery</tt> (default), <tt>prototype</tt>, <tt>rightjs</tt>
+* orm: <tt>datamapper</tt> (default), <tt>mongomapper</tt>, <tt>activerecord</tt>, <tt>sequel</tt>, <tt>couchrest</tt>
+
+The generator uses the <tt>bundler</tt> gem to resolve any application dependencies when the application is newly created.
+The necessary bundler command can be executed automatically through the generator with
+
+ $ padrino-gen demo_app . --run_bundler # alias -b
+
+or this can be done manually through executing command <tt>gem bundle</tt> in the terminal at the root of the generated application.
+If not executed manually, the bundling will be performed automatically the first time the application attempts to boot.
+Note that this command only has to be performed when the application is first generated or when the Gemfile is modified.
+
+The generator framework within padrino is extensible and additional components and tools can be added easily.
+This would be achieved through forking our project and reading through the code in <tt>/generators/sinatra_generator.rb</tt> and
+the setup instructions inside the relevant files within <tt>/generators/components/</tt>. We are happy to accept pull requests
+for additional component types not originally included (although helping us maintain them would also be appreciated).
+
+We are also planning to add generator actions such as:
+
+* Model generation (working for any of the available orms listed)
+* Routes generation
+* Mailer generation
+* Migrations generation
+
+See the wiki article for additional information: <...WIKI...>
== Copyright
Oops, something went wrong.

0 comments on commit 0b6a601

Please sign in to comment.