SmashingDocs

In your gemfile add the following to your test group:

gem 'smashing_docs', '~> 1.3.5'

Installation differs for RSpec/Minitest, so scroll to the appropriate section for guidance.

After you bundle, run:

rails g docs:install

SmashingDocs will be configured to run on all your controller tests with the default template.

If you're using RSpec and you haven't required rails_helper in your tests, do that now.

require 'rails_helper'

Run rails g docs:build_docs, and your docs will be waiting for you in the smashing_docs folder.

Add this to your rails_helper.rb It should go outside of other blocks (Do not place it inside the RSpec.configure block).

SmashingDocs.config do |c|
  c.template_file = 'smashing_docs/template.md'
  c.output_file   = 'smashing_docs/api_docs.md'
  c.run_all       = true
  c.auto_push     = false
  c.wiki_folder   = nil
end

Add the following content to spec_helper.rb inside the RSpec.configure block

# config.after(:suite) { SmashingDocs.finish! }

It should look like this

RSpec.configure do |config|
  # Existing code
  config.after(:each, type: :controller) do
    SmashingDocs.run!(request, response, true)
  end
  # config.after(:suite) { SmashingDocs.finish! }
end

Set the c.run_all line to false in rails_helper.rb

SmashingDocs.config do |c|
  # configs
  c.run_all       = false
  # configs
end

Then just add SmashingDocs.run!(request, response) to the tests you want to run

it "responds with 200" do
  get :index
  expect(response).to be_success
  SmashingDocs.run!(request, response)
end

Add the code from below to test_helper.rb:

class ActiveSupport::TestCase
  # Already existing code
  SmashingDocs.config do |c|
    c.template_file = 'smashing_docs/template.md'
    c.output_file   = 'smashing_docs/api_docs.md'
    c.run_all       = true
    c.auto_push     = false
    c.wiki_folder   = nil
  end
  # More code
end

class ActionController::TestCase < ActiveSupport::TestCase
  def teardown
    SmashingDocs.run!(request, response, true)
  end
end

MiniTest::Unit.after_tests { SmashingDocs.finish! }

Set the c.run_all line to false in test_helper.rb

SmashingDocs.config do |c|
  # configs
  c.run_all       = false
  # configs
end

Then just add SmashingDocs.run!(request, response) to specific tests

def get_index
  get :index
  assert response.status == 200
  SmashingDocs.run!(request, response)
end

If you used the auto-installer or copied the code from above, SmashingDocs will look for a template file located in smashing_docs/template.md

This template may be customized to fit your needs.

<%= request.method %>
<%= request.path %>
<%= request.params %>
<%= response.body %>
<%= information[:note] %>

By default, the docs are output to smashing_docs/api_docs.md in the Rails project. You can change this by altering the config in test_helper.rb (MiniTest) or rails_helper.rb(RSpec).

To leave certain tests out of the documentation, just add SmashingDocs.skip to the test.

it "responds with 200" do
  SmashingDocs.skip
  # test code
end

SmashingDocs will log all requests and responses by default, but you can add some optional parameters as well.

it "responds with 200" do
  SmashingDocs.information(:note, "This endpoint only responds on Tuesdays")
  # test code
end

You can store any information with :note, :message, or any other key you can think of. To access information in the template, just use <%= information[:key] %>

SmashingDocs can automatically push your generated docs to your project wiki.

To enable this feature

1. Clone your wiki repo from Github into the same parent folder as your app

Your folder structure should be

../projects/rails_app

../projects/my_rails_app.wiki

2. Set the name of your wiki folder (do not include '.wiki')

``` ruby
  SmashingDocs.config do |c|
    # configs
    c.wiki_folder = "my_rails_app"
  end
```

3. Set auto_push to true in rails_helper.rb or test_helper.rb

``` ruby
  SmashingDocs.config do |c|
    # configs
    c.auto_push = true
    # configs
  end
```

4. Build your docs with rails g docs:build_docs

If you prefer to have your docs built every time you run the test suite, and do not want to run the build command, then uncomment the SmashingDocs.finish line in your rails_helper or test_helper