Official Spree Documentaion
CSS Ruby JavaScript
Pull request Compare This branch is 665 commits behind spree:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.

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.


When contributing to the Spree documentation, it's important to make sure you understand your audience, and are speaking to them using appropriate terminology that they will both understand and appreciate.


Those reading these guides are likely intermediate- to advanced-level developers. They are likely comfortable with complex technical language and concepts.


The audience for guides in the /developer directory includes developers from beginners to advanced. They are expected to already be familiar with Ruby and Rails, but may not have as much experience with deployment and integration with external services.


Consumers of this documentation are developers with intermediate to advanced skills. They should already be well-versed in Ruby and Rails; familiar with the core Spree application; and have knowledge of integrating with external services.

Release Notes

Developers of all degrees of experience are the audience for these documents.


Admins and store owners are the ones most likely to be using this documentation. These guides are where developers can send their clients to teach them how to maintain their store and process orders.


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.

Markdown Conventions

It is helpful to standardize some markdown conventions so readers learn to recognize visual cues as they work their way through the documentation and tutorials. Following are the conventions used for the Spree documentation:

####Class Names####

When referencing the name of a class, it should be capitalized. If you are writing explanatory prose and not a section of code, the class name should be blocked out with tick (`) marks. For example:

To begin using your custom `User` class, you must first...

Having the namespace for the class is optional, but should be included when omitting it could cause confusion.

An instance of a class should be lowercase, normal font:

You can view all of the orders for a particular user.

####Buttons, Links, Section Names, Form Elements####

These should always reference the correct label and can have their names quoted. Examples:

  • Click the "Filter Results" button to update the results.
  • Follow the "Stock Transfers" link.
  • Information displayed in the "Purchase Funnel" section gives you information...
  • If you check "Receive Stock" while creating a new transfer...

####States, Attributes, Methods, Events, and Parameters#### When referring to the state of an object - an order, for example - the state name should be lowercase and set off with tick (`) marks. For example:

Orders that are in the `address` state do not have valid shipping and billing addresses assigned to them yet.

This same style is used for attribute names and their settings, method names, event names, parameter names, parameter settings, and data types.

####Path Names#### Path names should be set off with tick (`) marks, and should include enough of the directory structure to make it clear which file is being referenced. For example:

They are defined in `core/app/models/spree/app_configuration.rb`...

####Adding Emphasis#### Any text that needs to be emphasized should be in italics.

Only the shipping options in the _shipping_ address are presented.

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/addresses/index.html
  create  [0.01s]  output/changelog/index.html
  create  [0.02s]  output/countries/index.html
  create  [0.03s]  output/index.html
  create  [0.08s]  output/order/line_items/index.html
  create  [0.15s]  output/order/payments/index.html
  create  [0.02s]  output/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!


Standard deploy for the latest stable guides:

$ bundle exec cap deploy

To deploy the latest edge guides:

$ bundle exec cap deploy -S edge=true


  • Integrate through a simple app for live API calls.
  • Write a task for verifying JSON Resource examples against the actual API.