No description, website, or topics provided.
JavaScript Ruby Racket
Switch branches/tags
Nothing to show
Latest commit c2026ec Feb 12, 2013 @LBRapid LBRapid Fix lib/resources typo

This is a Spree API resource built with nanoc.

All submissions are welcome. To submit a change, fork this repo, commit your changes, and send us a pull request.


Ruby 1.9 is required to build the site.

Get the nanoc gem, plus kramdown for markdown parsing:

bundle install

You can see the available commands with nanoc:

nanoc -h

Nanoc has some nice documentation to get you started. Though if you're mainly concerned with editing or adding content, you won't need to know much about nanoc.


Not sure how to structure the docs? Here's what the structure of the API docs should look like:

# API title

## API endpoint title

    [VERB] /path/to/endpoint.json

### Parameters

: description

### Input (request json body)

<%= json :field => "sample value" %>

### Response

<%= headers 200, :pagination => true, 'X-Custom-Header' => "value" %>
<%= json :resource_name %>

Note: We're using Kramdown Markdown extensions, such as definition lists.

JSON Responses

We specify the JSON responses in ruby so that we don't have to write them by hand all over the docs. You can render the JSON for a resource like this:

<%= json :product %>

This looks up Spree::Resources::PRODUCT in lib/resources.rb.

Some actions return arrays. You can modify the JSON by passing a block:

<%= json(:issue) { |hash| [hash] } %>

Terminal blocks

You can specify terminal blocks with pre.terminal elements. It'd be nice if Markdown could do this more cleanly...

<pre class="terminal">
$ curl foobar

This isn't a curl tutorial though, I'm not sure every API call needs to show how to access it with curl.


Nanoc compiles the site into static files living in ./output. It's smart enough not to try to compile unchanged files:

$ nanoc compile
Loading site data...
Compiling site...
  create  [0.03s]  output/changes/index.html
  create  [0.00s]  output/CNAME
  create  [0.02s]  output/changes.atom
  create  [0.01s]  output/index.html
  create  [0.09s]  output/v1/addresses/index.html
  create  [0.01s]  output/v1/changelog/index.html
  create  [0.02s]  output/v1/countries/index.html
  create  [0.03s]  output/v1/index.html
  create  [0.08s]  output/v1/order/line_items/index.html
  create  [0.15s]  output/v1/order/payments/index.html
  create  [0.02s]  output/v1/order/shipments/index.html

Site compiled in 5.81s.

You can setup whatever you want to view the files. If you have the adsf gem, however (I hope so, it was in the Gemfile), you can start Webrick:

$ nanoc view
$ open http://localhost:3000

Compilation times got you down? Use autocompile!

$ nanoc autocompile

This starts a web server too, so there's no need to run nanoc view. One thing: remember to add trailing slashes to all nanoc links!


$ bundle exec cap deploy


  • Integrate through a simple app for live API calls.
  • Maybe add a nice TOC at the top of each page.
  • Write a task for verifying JSON Resource examples against the actual API.