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.
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
name
: 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.
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.
####Terminal Blocks####
You can specify terminal blocks by setting it off with ```bash. In addition, you can differentiate commands you are using from output returned by using the $ precursor for input and `=>` precursor for output.
$ irb
$ c = "Hello world"
$ c
=> "Hello world"```
####Special Blocks####
Certain blocks of text can be wrapped in sets of three characters, which will place them in divs with appropriate CSS classes. They are:
| *** | Notes. |
| !!! | Warnings. |
| $$$ | TODO's |
| --- | A title bar; especially useful for headings for code samples. |
### 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] } %>
## Development
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!
## Edge guides
Set `EDGE_DOCS=true` in an environment variable in order to generate the "edge" badge. You may need to remove any previously generated output for the change to take effect
$ export EDGE_DOCS=true
$ nanoc autocompile
## Deploy
Standard deploy for the latest stable guides:
$ bundle exec cap deploy
To deploy the latest edge guides:
$ bundle exec cap deploy -S edge=true
## TODO
* Integrate through a simple hurl.it app for live API calls.
* Write a task for verifying JSON Resource examples against the actual
API.