Skip to content

Instantly share code, notes, and snippets.

What would you like to do?


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


  Net::HTTP.start('') do |http|
    req ='/secret-page.html')
    req.basic_auth 'account', 'password'
    response = http.request(req)
  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.


This comment has been minimized.

Copy link

ianterrell commented May 24, 2010

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


This comment has been minimized.

Copy link
Owner Author

rubiii commented May 24, 2010

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


This comment has been minimized.

Copy link

psyho commented May 24, 2010

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.


This comment has been minimized.

Copy link

bmabey commented May 24, 2010

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.


This comment has been minimized.

Copy link

ignu commented May 24, 2010

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


This comment has been minimized.

Copy link

BJClark commented May 25, 2010

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.

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.