SmarfDoc

(Formerly 'DocYoSelf')

Too many docs spoil the broth.

SmarfDoc lets you turn your controller tests into API docs without making changes to your test suite or how you write tests.

Pop it into your test suite and watch it amaze.

Time for this project was provided by my employer, SmashingBoxes. What a great place to work!

Setup

In your gemfile: gem 'smarf_doc', group: :test, github: 'RickCarlino/smarf_doc'

In test_helper.rb:

SmarfDoc.config do |c|
  c.template_file = 'test/template.md.erb'
  c.output_file   = 'api_docs.md'
end

See test/fake_template.md for template examples.

To run doc generation after every controller spec, put this into your teardown method. Or whatever method your test framework of choice will run after every test.

Minitest Usage

Running it for every test case:

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

..or if you only want to run it on certain tests, try this:

def test_some_api
  get :index, :users
  assert response.status == 200
  SmarfDoc.run!(request, response)
end

Then put this at the bottom of your test_helper.rb:

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

Rspec Usage

Put this in your spec_helper and smoke it.

RSpec.configure do |config|
  config.after(:each, type: :controller) do
    SmarfDoc.run!(request, response)
  end

  config.after(:suite) { SmarfDoc.finish! }
end

Usage

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

Skipping documentation

def test_stuff
  SmarfDoc.skip
  # Blahhh
end

Adding notes

def test_stuff
  SmarfDoc.note "안녕하세요. This is a note."
  # Blahhh
end

TylerRockwell / smarf_doc