potassium 1.3.5 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0bc9e2e96b1fa0d0f800bc2bf23617765c9c5b68
-  data.tar.gz: a844e31692d312c32791da3c08d1e95fb5ea661b
+  metadata.gz: 3e42b19285cfdc9b98d8481a021a68a08dcb7fb6
+  data.tar.gz: faa3f6cefda09e5ca429b7d542b39ffdff80d24a
 SHA512:
-  metadata.gz: 6f67bdf66ad59d474cd4d9d29e38ccfc9780a5a56087baaf8b9c80c3121c49e391daf5830775a2e698e13ab238e75a7bcdc5a9d4750e979b1989c8ba5aef265a
-  data.tar.gz: 66a2c03ebbca40f554992b4a7cb596da2e8b876242164dfdd58b360caaa468b7376a0e679a2a6e87c61362d5302db72b23e28abedbe1ff7e71169e277d6fa18f
+  metadata.gz: 71899b46a6e1006027a2fa193f3eb802ef6fe0b8cea1be3cb9def2dbb4e9312cdb97ee3dc643893761e7a6a1c29023606ba9e225ef5a5939743c5dcd789a500e
+  data.tar.gz: 95725c1f5db91367b0b85eab121bab9ca47ae49b8f97e17c3b229d98897046eb2712f3cc8a9d134710da8e93abea29854b136129cf56dd95bf8fd21cb417624d

data/.gitignore

@@ -13,3 +13,4 @@
 *.a
 mkmf.log
 .DS_Store
+.rubocop-http*

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--require spec_helper
+--format=doc

data/.rubocop.yml

@@ -1,3 +1,3 @@
 inherit_from:
-  - ~/.rubocop.yml
+  - https://raw.githubusercontent.com/platanus/hound/platanus/config/style_guides/platanus/ruby.yml
   - .ruby_style.yml

data/.ruby_style.yml

@@ -1,2 +1,6 @@
-AllCops:
-  RunRailsCops: false
+Rails:
+  Enabled: false
+Metrics/MethodLength:
+  Enabled: false
+Metrics/AbcSize:
+  Enabled: false

data/CHANGELOG.md

@@ -2,10 +2,28 @@
 
 ## Unreleased
 
-Features:
+## 2.0.0
 
+Features:
+  - Use `.env` instead of `.rbenv-vars`
+  - Use Puma instead of unicorn
   - Gets ruby version from http://ruby.platan.us/latest
   - Adds the install command
+  - Adds heroku buildpack support using the [multi buildpack](multi-buildpack)
+  - Adds `rack-timeout` to prevent long running requests
+  - Adds [deploy-tasks buildpack](deploy-tasks) mainly to perform migrations, [#39]
+  - Add Delayed Jobs to handle background processes, [#41]
+  - Adds continuous integration using [CircleCI](https://circleci.com)
+  and docker, [#51]
+  - Adds heroku app creation to the heroku recipe, [#60]
+  - Adds github repo creation through hub
+  - Build a project Readme based on the potassium installed recipes, [#61]
+
+[multi-buildpack]: http://github.com/ddollar/heroku-buildpack-multi
+[deploy-tasts]: http://github.com/gunpowderlabs/buildpack-ruby-rake-deploy-tasks
+[#39]: http://github.com/platanus/potassium/pull/39
+[#41]: http://github.com/platanus/potassium/pull/41
+[#51]: http://github.com/platanus/potassium/pull/51
 
 ## 1.3
 

data/README.md

@@ -1,4 +1,4 @@
-# Potassium
+# Potassium [![Circle CI](https://circleci.com/gh/platanus/potassium.svg?style=svg)](https://circleci.com/gh/platanus/potassium)
 
 A Rails application generator from [Platanus](https://github.com/platanus), inspired by [Suspenders](https://github.com/thoughtbot/suspenders).
 
@@ -14,15 +14,19 @@ You have to install Potassium globally:
 
 Use the `potassium create` command to create a new project:
 
-    $ potassium create project-name
+    $ potassium create <project-name>
 
-It's important to note that it will perform a version check before running to ensure that you're using the latest potassium. Also, if you feel that it's too slow, you may need to update rubygems: `gem update --system`.
+> It's important to note that it will perform a version check before running to ensure that you're using the latest potassium. Also, if you feel that it's too slow, you may need to update rubygems: `gem update --system`.
 
 ### Adding recipes to an existing project
 
 Use the `potassium install` command to add a recipe to a project:
 
-    $ potassium install i18n
+    $ potassium install devise
+
+You can force an already installed recipe by passing the `--force` argument
+
+    $ potassium install devise --force
 
 You can run the command on its own to view all the available recipes and select one:
 
@@ -32,8 +36,8 @@ You can run the command on its own to view all the available recipes and select
 
 Potassium Rails apps includes the following gems and technologies:
 
-- [rbenv](https://github.com/sstephenson/rbenv) for managing the project's ruby version.
-- [rbenv-vars](https://github.com/sstephenson/rbenv-vars) for keeping secrets and by-server configurations.
+- [Ruby](https://www.ruby-lang.org) Set the project ruby version based on http://ruby.platan.us/latest
+- [dotenv](https://github.com/bkeepers/dotenv) load environmental variables in development
 - [Bower](http://bower.io) for frontend assets packages.
 - [EditorConfig](http://editorconfig.org) for keeping all our editor configurations the same.
 - [pry](http://pryrepl.org) and [pry-byebug](https://github.com/deivid-rodriguez/pry-byebug) for a less painful debugging experience.
@@ -41,6 +45,9 @@ Potassium Rails apps includes the following gems and technologies:
 - [FactoryGirl](https://github.com/thoughtbot/factory_girl) for test factories.
 - [Guard](http://guardgem.org) for continuous testing and other watch-related tasks.
 - [AWS-SDK](https://github.com/aws/aws-sdk-ruby) for file uploads, sdks, etc and because we use AWS.
+- [Puma](https://github.com/puma/puma) to serve HTTP requests
+- [Rack Timeout](https://github.com/heroku/rack-timeout) to abort requests that are
+  taking too long
 
 The following optional integrations are added too:
 
@@ -49,95 +56,93 @@ The following optional integrations are added too:
 - [ActiveAdmin](http://activeadmin.info) for admin interfaces.
 - [ActiveAdminAddons](https://github.com/platanus/activeadmin_addons) for some help with ActiveAdmin.
 - [Pundit](https://github.com/elabs/pundit) for role-based authorization.
+- [DelayedJob](https://github.com/collectiveidea/delayed_job) to execute longer tasks in the background.
 
-And, finally, we also include optional API support, which includes:
-
-- [Responders](https://github.com/plataformatec/responders) for dry-ing our api controllers.
-- [Versionist](https://github.com/bploetz/versionist) for some flexible api versioning.
-- [ActiveModel::Serializers](https://github.com/rails-api/active_model_serializers) for record serialization.
-- [Simple Token Authentication](https://github.com/gonzalo-bulnes/simple_token_authentication) for stateless API authentication.
-
-## Contributing
-
-### How do I add something new to Potassium?
-
-In the [lib/potassium/templates/application](lib/potassium/templates/application) folder, you will find [the template](lib/potassium/templates/application/template.rb). You should follow the next conventions to add something:
-
-*__NOTE:__ If you only want to use Potassium but not to add something new, the next parts can be easily skipped.*
+A few more things are added to the project:
 
-#### Ask
+- A [low database connection pool limit][pool]
+- Setup [Rubocop][rubocop] configuration with Platanus [style guides][rubocop-platanus]
+- Setup [Hound CI][platanus-hound] configuration, with Platanus flavour
+- Setup continuous integration in [CircleCI](circle-ci) to run tests.
+- Create the github repository for the project (it used `hub` under the hood)
+- A `bin/setup` script to setup things on a newly cloned project
+- A `bin/cibuild` script to run continuous integration build on CI
 
-If you need to ask something to the user before doing something, follow the next steps:
+[pool]: https://devcenter.heroku.com/articles/concurrency-and-database-connections
+[rubocop]: https://github.com/bbatsov/rubocop
+[rubocop-platanus]: https://raw.githubusercontent.com/platanus/hound/platanus/config/style_guides/platanus/ruby.yml
+[platanus-hound]: http://monkeyci.platan.us
 
-1. Create a ruby file on the [recipes/asks](lib/potassium/templates/application/recipes/asks) folder.
-2. Then, ask something using the methods defined in [Inquirer](https://github.com/arlimus/inquirer.rb), that we use by default. Use the [DSL](docs/dsl.md) to store some information.
-3. Finally, register the **ask** you created in [the template](lib/potassium/templates/application/template.rb):
+### API support
 
-  ```ruby
-  run_action(:asking) do
-    # ...
-    eval_file "recipes/asks/my_ask.rb"
-  end
-  ```
+The optional API support includes:
 
-#### Install
-
-Now, to add some behavior, thanks to the [DSL](docs/dsl.md) we have a kind of standard flow of what happens when a new project is created. To understand this better, please read [the template](lib/potassium/templates/application/template.rb). The structure looks like this:
+- [Responders](https://github.com/plataformatec/responders) for dry-ing our api controllers.
+- [Versionist](https://github.com/bploetz/versionist) for some flexible api versioning.
+- [ActiveModel::Serializers](https://github.com/rails-api/active_model_serializers) for record serialization.
+- [Simple Token Authentication](https://github.com/gonzalo-bulnes/simple_token_authentication) for stateless API authentication.
 
-1. Clean the Gemfile and add the base gems that rails needs to work.
-2. Run all the **asks** recipes.
-3. Execute all the **recipes**, that are ruby files stored on the [recipes](lib/potassium/templates/application/recipes) folder. They specify what gems are needed and registers callbacks based on this process, usually to execute things after the gem installation happened or after some other recipe finished his work.
-4. Install the gems, filling the Gemfile before with all the gathered gems.
-5. Finally, create the database.
+### Heroku
 
-The main step is the 3rd, when we run the recipes. A recipe can do anything (because is a ruby script) but their responsability should be to gather gems and register callbacks for the process.
+When you choose to deploy to heroku a few extra things are added for the project.
 
-For example, if we want to create an optional recipe to add a gem called `banana_split` that needs to run a generator, we can do the following.
+  - Adds the [Rails Stdout Logging][logging-gem] gem
+    to configure the app to log to standard out,
+    which is how [Heroku's logging][heroku-logging] works.
+  - Adds a [Procfile][procfile] to define the processes to run in heroku
+  - Setup continuous integration using docker and herokuish to maintain better
+    parity between testing and production environments
+  - Adds a `.buildpacks` file with the default buildpacks to use. It use the
+    following buildpacks:
 
-1. Create the **ask** file:
+| index | buildpack | description |
+|-------|-----------|-------------|
+| 1.    | [bower][heroku-buildpack-bower] | to make sure `bower install` run before the assets precompilation task |
+| 2.    | [ruby-version][heroku-buildpack-ruby-version] | to support the use of `.ruby-version` file to instruct heroku which ruby version to use |
+| 3.    | [ruby][heroku-buildpack-ruby] | the base buildpack to run ruby applications |
+| 4.    | [ruby-deploy-tasks][buildpack-deploy-tasks] | to run rake task after the deployment is complete, for example `db:migrate` |
 
-  ```ruby
-  # application/recipes/ask/banana_split.rb
-  use_banana_split = Ask.confirm("Do you want to use Banana Split?")
-  set(:use_banana_split, true) if use_banana_split
-  ```
+Also the heroku applications are created
 
-2. Then, register the **ask**:
+  - Creates a `staging` and `production` applications
+  - Creates a pipeline and assign the above application to the `staging`
+    and `production` stages.
+  - Setup initial configuration variables
+  - Set the application buildpack to the [multi-buildpack][heroku-buildpack-multi]
+  - Set **deploy-tasks** buildpack is setup to run `rake db:migrate` after each deploy
 
-  ```ruby
-  run_action(:asking) do
-    # ...
-    eval_file "recipes/asks/banana_split.rb"
-  end
-  ```
+You'll need to manually
 
-3. Create the **recipe**. Register a gem using `gather_gem` and create a callback to be called after the `gem_install` action succeded to run the generator. `gem_install` is one of the main actions that should be easily visible with a sneak peek in [the template](lib/potassium/templates/application/template.rb).
+  - Connect the pipeline with the github repository
+  - Assign a branch to each stage for auto deployments
+  - Enable deploy after CI pass
 
-  ```ruby
-  # application/recipes/banana_split.rb
-  if get(:use_banana_split)
-    gather_gem('banana_split', '~> 1.2')
+### Continuous Integration
 
-    after(:gem_install) do
-      generate('banana_split:install')
-    end
-  end
-  ```
+In order to CicleCI start building the project on each push you need tell circle ci.
+Go to https://circleci.com/add-projects, choose the repository from the list and hit
+**Build Project**
 
-4. Register the **recipe**:
+### Hound CI
 
-  ```ruby
-  run_action(:recipe_loading) do
-    # ...
-    eval_file "recipes/banana_split.rb"
-  end
-  ```
+In order to Hound start checking your project's PRs you need enable that repository.
+Go to https://monkeyci.platan.us, choose the repository from the list and hit
+**Activate**
 
-5. Ready, let's start working on your new project.
+[logging-gem]: https://github.com/heroku/rails_stdout_logging
+[heroku-logging]: https://devcenter.heroku.com/articles/logging#writing-to-your-log
+[procfile]: https://devcenter.heroku.com/articles/procfile
+[heroku-buildpack-ruby-version]: http://github.com/platanus/heroku-buildpack-ruby-version
+[heroku-buildpack-bower]: http://github.com/platanus/heroku-buildpack-bower
+[heroku-buildpack-ruby]: http://github.com/heroku/heroku-buildpack-ruby
+[heroku-buildpack-multi]: http://github.com/ddollar/heroku-buildpack-multi
+[buildpack-deploy-tasks]: http://github.com/gunpowderlabs/buildpack-ruby-rake-deploy-tasks
+[circle-ci]: https://circleci.com
 
-#### The DSL
+## Contributing
 
-To see further documentation of what we added to the rails template's DSL, check the [DSL documentation](docs/dsl.md). Remember that the DSL we are documenting is an extension over the [Rails Application Template DSL](http://edgeguides.rubyonrails.org/rails_application_templates.html), that itself is a dsl based on [Thor](https://github.com/erikhuda/thor/wiki).
+If you want to add functionality please go to
+the [contributing](/docs/CONTRIBUTING.md)
 
 ## Credits
 

data/circle.yml

@@ -0,0 +1,9 @@
+machine:
+  ruby:
+    version: 2.3.0
+  services:
+    - docker
+
+dependencies:
+  override:
+    - bundle install

data/docs/CONTRIBUTING.md

@@ -0,0 +1,132 @@
+# Contributing
+
+## How do I add something new to Potassium?
+
+### Template
+
+In the [lib/potassium/templates](/lib/potassium/templates) folder, you will find [the template][the-template].
+
+Now, to add some behavior, thanks to the [DSL](/docs/DSL.md) we have a kind of standard flow of what happens when a new project is created. To understand this better, please read [the template][the-template]. The structure looks like this:
+
+1. Clean the `Gemfile` and add the base gems that rails needs to work.
+2. Run all the `ask` methods from the recipes.
+3. Execute all the `create` methods from the recipes, that are ruby classes stored on the [recipes](/lib/potassium/recipes) folder. Here you can specify what gems are needed and register callbacks based on this process, usually to execute things after the gem installation happened or after some other recipe finished his work.
+4. Install the gems, filling the `Gemfile` before with all the gathered gems.
+5. Finally, create the database.
+
+The main step is the 3rd, when we call the `create` methods from the recipes. A recipe can do anything (because is a ruby script) but their responsability should be to gather gems and register callbacks for the process.
+
+### Recipe
+
+The recipes are classes defined in the `Recipes` module that inherit from
+`Rails::AppBuilder` and by convention can implement some of the following
+methods `ask`, `create` and `install`. So they took this form.
+
+```ruby
+class Recipes::MyRecipe < Rails::AppBuilder
+  def ask
+    #...
+  end
+
+  def create
+    #...
+  end
+
+  def install
+    #...
+  end
+end
+```
+
+The recipes should be created in the `lib/potassium/recipes` folder.
+
+#### Methods
+
+For example, if we want to create an optional recipe to add a gem called
+`banana_split` that needs to run a generator, we can do the following.
+
+##### | `ask`
+
+This method is used if you need to ask something to the user before doing something.
+
+1. Use the [answer method](DSL.md#answer-helpers) to ask something using the methods defined in [Inquirer](https://github.com/arlimus/inquirer.rb), that we use by default. Use the [DSL](/docs/dsl.md) to store some information.
+
+    ```ruby
+    def ask
+      use_banana_split = answer(:banana_split) do
+        Ask.confirm("Do you wan to use Banana Split?")
+      end
+      set(:use_banana_split, true) if use_banana_split
+    end
+    ```
+
+2. Then, register the question you created in [the template][the-template]:
+
+    ```ruby
+    run_action(:asking) do
+      # ...
+      ask :myRecipe
+    end
+    ```
+
+##### | `create`
+
+We'll call this method to add specific functionality to the rails project.
+
+1. In the `create` method register a gem using `gather_gem` and create a callback to be called after the `gem_install` action succeded to run the generator. `gem_install` is one of the main actions that should be easily visible with a sneak peek in [the template][the-template].
+
+    ```ruby
+    def create
+      if get(:use_banana_split)
+        gather_gem('banana_split', '~> 1.2')
+
+        after(:gem_install) do
+          generate('banana_split:install')
+        end
+      end
+    end
+    ```
+
+2. Then, register the recipe creation in [the template][the-template]:
+
+    ```ruby
+    run_action(:recipe_loading) do
+      # ...
+      create :banana_split
+    end
+    ```
+
+##### | `install`
+
+The install method will be called when you use the `install` command from potassium.
+For example if you run `portassium install devise` this will use
+[the recipe template](/lib/potassium/templates/recipe.rb) to load an execute the
+`install` method for the **devise** recipe.
+
+You can defined the main functionallity of a recipe in a private method and call
+it from the `create` and `install` methods.
+
+```ruby
+def install
+  if gem_exists?(/banana_split/)
+    info "Banana Split is already installed"
+  else
+    install_banana
+  end
+end
+
+private
+
+def install_banana
+  #...
+end
+```
+
+
+## The DSL
+
+To see further documentation of what we added to the rails template's DSL, check the [DSL documentation](/docs/DSL.md).
+
+> Remember that the DSL we are documenting is an extension over the [Rails Application Template DSL](http://edgeguides.rubyonrails.org/rails_application_templates.html), that itself is a dsl based on [Thor](https://github.com/erikhuda/thor/wiki).
+
+[the-template]: /lib/potassium/templates/application.rb

data/docs/{dsl.md → DSL.md}

@@ -1,10 +1,56 @@
-## The DSL
+# The DSL
+
 
 The DSL to extend and add recipes defines methods divided in mixins called helpers.
 
+## The helpers
+
+- [Templates](#template-helpers)
+- [Answers](#answer-helpers)
+- [Variable](#variable-helpers)
+- [Environment](#environment-helpers)
+- [Callback](#callback-helpers)
+- [Gem](#gem-helpers)
+- [Info](#info-helpers)
+- [Readme](#readme-helpers)
+
 ### Template Helpers
 
-#### eval_file(file)
+##### | `ask(recipe_name)`
+
+Loads the recipe and execute its `ask` method.
+
+```ruby
+ask :devise
+```
+
+##### | `create(recipe_name)`
+
+Loads the recipe and execute its `create` method.
+
+```ruby
+create :devise
+```
+
+##### | `install(recipe_name)`
+
+Loads the recipe and execute its `install` method. If the recipe implements
+a `installed?` method it will check first if it is already installed. You can
+force the installation by passing the `--force` argument on the cli.
+
+```ruby
+install :devise
+```
+
+##### | `load_recipe(recipe_name)`
+
+Loads and return the recipe.
+
+##### | `force?`
+
+Whether the `--force` argument was passed from the cli.
+
+##### | `eval_file(file)`
 
 Just evals a file from the source path of this folder. Example:
 
@@ -14,7 +60,7 @@ eval_file('recipes/database.rb')
 
 You can use any variable name you want in the body of the recipe because all the code loaded in each recipe is wrapped inside a method that is executed thereafter.
 
-#### erase_comments(file)
+##### | `erase_comments(file)`
 
 Erase the comments from a file in the rails application created. Example:
 
@@ -22,9 +68,22 @@ Erase the comments from a file in the rails application created. Example:
 erase_comments('Gemfile')
 ```
 
+### Answer Helpers
+
+##### | `answer(key, &block)`
+
+Defines a key to store the answers. In the fallback you can pass a block
+with the code that will make the question.
+
+```ruby
+answer(:devise) do
+  Ask.confirm("Do you want to install devise")
+end
+```
+
 ### Variable Helpers
 
-#### set(key, value)
+##### | `set(key, value)`
 
 Defines a variable to use in different parts of the template. It's important to note that this was preferred over using standard instance variables because the rails template context is not fully controlled by us and to use arbitrary standard instance variables can lead to name clashing. Example:
 
@@ -32,7 +91,7 @@ Defines a variable to use in different parts of the template. It's important to
 set('fruit', 'platanus')
 ```
 
-#### get(key)
+##### | `get(key)`
 
 Retrieves a variable that was defined with `set`. Example:
 
@@ -40,7 +99,7 @@ Retrieves a variable that was defined with `set`. Example:
 get('fruit') == 'platanus'
 ```
 
-#### equals?(key, value)
+##### | `equals?(key, value)`
 
 Wrapps the pattern `get(key) == value`. Example:
 
@@ -52,7 +111,7 @@ equals?('fruit', 'platanus') # true
 
 ### Environment Helpers
 
-#### set_env(key, value)
+##### | `set_env(key, value)`
 
 Stores a future environment helper in the key `default_env` to be used in some way (the `.rbenv-vars` file is the only use right now). To help ensure that the execution of some rake commands in the end of the installation is correct, this sets the value as a real environment variable too. In this way, running `rake db:create` within the template will use the same environment variables that will use later, while running. Example:
 
@@ -60,7 +119,7 @@ Stores a future environment helper in the key `default_env` to be used in some w
 set_env('DB_USER', 'root')
 ```
 
-#### get_env(key)
+##### | `get_env(key)`
 
 Get the previously stored variable stored with `set_env` with the name of the key. Example:
 
@@ -68,7 +127,7 @@ Get the previously stored variable stored with `set_env` with the name of the ke
 get_env('DB_USER')
 ```
 
-#### default_env(hash = {})
+##### | `default_env(hash = {})`
 
 This stores all the pairs of a hash as environment variables. Example:
 
@@ -84,7 +143,7 @@ default_env({
 
 This helpers helps to organize the flow inside the template between multiple recipes. They ensure that the template runs in order and help injecting callbacks before and after important actions. For example, a recipe may want to register something to happen after the gem installation and something to happen after the database creation.
 
-#### run_action(action_name, &block)
+##### | `run_action(action_name, &block)`
 
 Runs a block with the registered callbacks for the action named as the action_name parameter. Example:
 
@@ -95,7 +154,7 @@ run_action(:gem_install) do
 end
 ```
 
-#### after(action_name, wrap_in_action: false, &callback)
+##### | `after(action_name, wrap_in_action: false, &callback)`
 
 This registers a callback to happen after an action happened. The `wrap_in_action` parameter can be used to wrap the callback in a `run_action` call. Example:
 
@@ -124,7 +183,7 @@ after(:gem_install) do
 end
 ```
 
-#### before(action_name, wrap_in_action: false, &callback)
+##### | `before(action_name, wrap_in_action: false, &callback)`
 
 This registers a callback to happen after an action happened. The `wrap_in_action` parameter can be used to wrap the callback in a `run_action` call. Example:
 
@@ -136,7 +195,7 @@ run_action(:gem_install) do
 end
 
 before(:gem_install) do
-  say "We are going to run gem install now", :green
+  success "We are going to run gem install now"
 end
 ```
 
@@ -149,7 +208,7 @@ The process with the gems installation is different from the standard Rails one.
 3. Through the loading of the recipes, add gems to the same hash.
 4. Using `build_gemfile` we build the gemfile from that information in a way that makes the Gemfile to be clean.
 
-#### gather_gem(name, *attributes)
+##### | `gather_gem(name, *attributes)`
 
 The attributes are the same as the attributes of the `gem` method of the Rails Templates. This adds a gem to the gem information but doesn't add it to the Gemfile yet. Example:
 
@@ -157,7 +216,7 @@ The attributes are the same as the attributes of the `gem` method of the Rails T
 gather_gem 'activeadmin', github: 'activeadmin'
 ```
 
-#### gather_gems(*environments, &block)
+##### | `gather_gems(*environments, &block)`
 
 Calls the block inside a block with the specified environments. It adds those gems as gems of those environments, so they are added in the correct place in the Gemfile. Again, everything is in memory and it's just stored in a final step, so we don't repeat groups in the final Gemfile. Example:
 
@@ -167,7 +226,7 @@ gather_gems(:development, :test) do
 end
 ```
 
-#### discard_gem(name)
+##### | `discard_gem(name)`
 
 This discard a previously added gem from everywhere. Example:
 
@@ -175,7 +234,7 @@ This discard a previously added gem from everywhere. Example:
 discard_gem('sqlite3')
 ```
 
-#### clean_gemfile
+##### | `clean_gemfile`
 
 This removes everything from the Gemfile, adds the `source 'https://rubygems.org'` line in the top, reads from the `gemfile_entries` array, which holds the original gems that rails created, and add them to the hash of gems. Example:
 
@@ -186,7 +245,7 @@ run_action(:cleaning) do
 end
 ```
 
-#### build_gemfile
+##### | `build_gemfile`
 
 It inserts the gems stored in memory inside the Gemfile, filling it cleanly. Example:
 
@@ -196,3 +255,72 @@ run_action(:gem_install) do
   run "bundle install"
 end
 ```
+
+### Info Helpers
+
+##### | `success(message)`
+
+To show success messages through standard output.
+
+```ruby
+success("gem installed!")
+```
+
+##### | `error(message)`
+
+To show error messages through standard output.
+
+```ruby
+error("error trying to create installation file")
+```
+
+##### | `info(message)`
+
+To show info messages through standard output.
+
+
+```ruby
+info("ActiveAdmin is already installed")
+```
+
+### Readme Helpers
+
+After running the potassium's `create` command, a custom `README.md` file will be generated with recipes you chose.
+Each recipe defines a "chunk" of that file. To do this, first you need to fill the [README.yml](/lib/potassium/assets/README.yml) file with desired definitions. Then, execute one of the following methods:
+
+##### | `add_readme_header(header, iterpolation_values)`
+
+If, for example, you want to add the style guide header, you need to do:
+
+```yml
+readme:
+  headers:
+    style_guide:
+      title: "Style Guides"
+      body: "The style guides are enforced through a self hosted version of..."
+```
+
+Then, in the recipe:
+
+```ruby
+add_readme_header(:style_guide)
+```
+
+##### | `add_readme_section(header, section, iterpolation_values)`
+
+To add header's sections. Paperclip, for example:
+
+```yml
+readme:
+  headers:
+    internal_dependencies:
+      title: "Internal dependencies"
+      sections:
+        paperclip:
+          title: "Uploads"
+          body: "For managing uploads, this project uses..."
+```
+
+```ruby
+add_readme_section(:internal_dependencies, :paperclip)
+```