Permalink
Switch branches/tags
Nothing to show
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
59 lines (48 sloc) 2.21 KB
title
Executable documentation

Erudite logo

Back in 1999, Tim Peters released doctest for Python. His motivation was simple:

  • Examples are priceless.
  • Examples that don't work are worse than worthless.
  • Examples that work eventually turn into examples that don't.

Recently, I've been working on many small side projects. I found myself with the same motivation as Mr. Peters. Since most of my projects were written in Ruby, I looked for a doctest gem. Unfortunately I didn't like what I found.

From what I can tell, rubydoctest is the de facto standard. It doesn't appear to be actively maintained, and it has a couple glaring omissions, like ellipsis wildcards and expected exceptions. I considered forking it to fix these issues, but ultimately decided to create my own gem instead.

This made sense to me because my aims are slightly different. I want a tool that can be used to write doctests, but it should also support a kind of literate programming. In particular, I should be able to feed it a project's README.md and it should run that as a test. This is inspired by Simon Hengel's tool markdown-unlit.

My own tool, Erudite, isn't as robust as either rubydoctest or markdown-unlit yet. Even so, it's be useful for testing. I can fire up the executable and paste in code from a README.md. It'll do all the work to determine if that code is valid or not.

$ bundle exec erudite
>> require 'stoplight'
=> true
>> Stoplight.data_store
=> #<Stoplight::DataStore::Memory:0x... @data={}>
- PASS
- PASS

I'm looking forward to rounding out Erudite's feature set, and I hope you find it useful. Check out its project page or the source on GitHub