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.

Python's doctest is similar in form and function. There's a wealth of user experience that can be drawn from that project.

http://docs.python.org/library/doctest.html

I think I heard of it before. Would love to have something similar in Ruby.

Definitely check out Python's doctest - it assumes that the examples are "copy-patsed" from console and verifies that they do actually work as advertised. This is very useful IMHO.

FYI, Ruby does have a doctest. I've used it in the past for small projects and have been happy with it. I'm sure it isn't mature as python's but it is pretty decent.

You may also want to go the other way. Meaning, take your specs and put them into your documentation. The yard-spec plugin is an example of this. The best example I have seen of specs being inlined with documentation is Ioke's docs.

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.