testable_examples.rdoc

Hi,

I would love to hear your opinion on the idea of “combining RDoc and RSpec to create testable documentation”. Let me explain:

Given you have several RDoc files like this one:

= Examples

Some example code snippets.

== Authentication

Supported authentication methods:

* HTTP basic authentication

Example:

  Net::HTTP.start('www.example.com') do |http|
    req = Net::HTTP::Get.new('/secret-page.html')
    req.basic_auth 'account', 'password'
    response = http.request(req)
  end

1. These RDoc files are parsed and code-blocks followed by a certain keyword (like “Example:” are saved for step 3.

2. An HTML documentation based on the RDoc files is generated, just like you would create an RDoc task via Rake::RDocTask and run “rake rdoc”. Nothing special here.

3. The code-blocks extracted from the RDoc files will be made accessable to some RSpec tests and run to verify they actually work.

I know this might be a lot of work, but it would allow you to create a fairly decent documentation along with examples of code that actually work.

Also I don’t know if it’s the best idea, but it’s certainly worth starting a discussion. Separating code from documentation (and keeping the documentation up to date) is pretty difficult, so by combining both life might be a little easier.

I appreciate any comments, ideas and feedback. I’m not aware of approach to combine documentation and tested examples, so please let me know if I’m missing something.

i heard you like specs so i put some specs in your specs

When I worked at Chargify (and I believe they still do this) we wrote Cucumber tests for our API, then published the tests because they made good documentation.

http://support.chargify.com/faqs/api/api-coupons

I'd rather write RSpecs and Cucumber tests that generate documentation than write documentation that also tested the code. So, instead of RDoc => RSpec I prefer RSpec => RDoc. This would also have the benefit of being able to mark certain tests as "nodoc" so you don't get the edge-case bloat constellationsoft was talking about.