thoughtworks/pacto — pull request #90 by maxlinc (2014-01-16 17:00:21+00:00)
Title: Trying out docco

*WIP: but mergeable if you really feel like it*

Requires [docco](https://github.com/jashkenas/docco), installed via npm. There is a ruby port (rocco), but it doesn't have as many features and the styling is currently broken.

You can generate documentation by runnning:
```bash
$ npm install -g docco
$ docco samples.rb
$ docco contract.js
```

The contract.js is really supposed to be contract.json, but you can't use comments with json. You can also try the different layouts: -l linear, -l parallel or -l classic.

Also, since it's just code ("literate programming") you can run `bundle exec ruby samples.rb` to make sure the samples are still valid. It would also be possible to use contract.rb.md with docco, which would let github render it as markdown and run the code with [this gist](https://gist.github.com/hecticjeff/5034580). The advantage of that approach would be that GitHub would render it as Markdown instead of code.