Update docs for new release.

source/guides/getting_started/hanami.html.md.erb

@@ -64,6 +64,37 @@ module Foo
 end
 ```
 
+5. Extend your actions to use jsonapi-rb:
+
+When using jsonapi-rb with Hanami (via the jsonapi-hanami gem), enabling of
+jsonapi-rb features is opt-in, and is done by including
+`JSONAPI::Hanami::Action` in your actions.
+Rendering is done by setting options directly on the controller action instance.
+The primary data is set via the `self.data` setter.
+
+Example:
+
+```ruby
+module API::Controllers::Posts
+  class Create
+    include API::Action
+    include JSONAPI::Hanami::Action
+
+    expose :url_helpers
+
+    def call(params)
+      # ...
+      @url_helpers = routes  # Will be available inside serializable resources.
+
+      self.data = posts
+      self.include = [:author, comments: [:author]]
+      self.fields  = { users: [:name, :email],
+                       posts: [:title, :content] }
+    end
+  end
+end
+```
+
 ## Examples
 
 <%= partial 'peeks/hanami' %>

source/guides/getting_started/index.html.md

@@ -0,0 +1,22 @@
+---
+layout: guides
+---
+# Getting started
+
+jsonapi-rb works by defining *serializable resources* for your business objects,
+which describe how to serialize a model of a given type in a given serialization
+context.
+
+The *renderer* then builds a JSON API document from your business objects.
+In order to do so, it needs to find for each type of model the corresponding
+serializable resource class, instantiate it, and then combine all the JSON API
+representations of isolated resources.
+
+Some context can be forwarded to the serializable resources: the *exposures*,
+specified when calling the renderer, are available within the serializable
+resource as instance variables.
+
+- [Plain Ruby](/guides/getting_started/plain_ruby.html)
+- [Ruby on Rails](/guides/getting_started/rails.html)
+- [Hanami](/guides/getting_started/hanami.html)
+- [Sinatra](/guides/getting_started/sinatra.html)

source/guides/getting_started/plain_ruby.html.md.erb

@@ -3,8 +3,47 @@ layout: guides
 ---
 # Getting started - Plain ruby
 
-Soon
+Once your [serializable resources](/guides/serialization) are defined, building
+a JSON API document from your business objects is straightforward.
 
-## Examples
+When using jsonapi-rb in plain ruby (or from within a framework outside of a
+controller), building documents is done by calling the `render` method of a
+`JSONAPI::Serializable::Renderer` instance.
 
-<%= partial 'peeks/plain' %>
+For a comprehensive list of renderer options, see
+[Renderer options](/guides/serialization/rendering.html).
+
+## Rendering resources
+
+```ruby
+renderer = JSONAPI::Serializable::Renderer.new
+
+renderer.render(posts,
+                class: { Post: SerializablePost, User: SerializableUser,
+                         Comment: SerializableComment },
+                include: [:author, comments: [:author]],
+                fields:  { users: [:name, :email],
+                           posts: [:title, :content] })
+```
+
+## Rendering relationships
+
+```ruby
+renderer = JSONAPI::Serializable::Renderer.new
+
+renderer.render(posts, relationship: :comments
+                class: { Post: SerializablePost, User: SerializableUser,
+                         Comment: SerializableComment },
+                include: [comments: [:author]],
+                fields:  { users: [:name, :email],
+                           posts: [:title, :content] })
+```
+
+## Rendering errors
+
+```ruby
+renderer = JSONAPI::Serializable::Renderer.new
+
+renderer.render_errors(errors,
+                       class: { Hash: SerializableErrorHash })
+```

source/guides/getting_started/rails.html.md.erb

@@ -3,8 +3,100 @@ layout: guides
 ---
 # Getting started - Ruby on Rails
 
-Soon
+Start by adding the following to your `Gemfile`:
 
-## Examples
+```ruby
+gem 'jsonapi-rails'
+```
 
-<%= partial 'peeks/rails' %>
+Then, once your [serializable resources](/guides/serialization) are defined, building
+a JSON API document from your business objects is straightforward: simply pass them
+to the `render` method.
+
+For a comprehensive list of renderer options, see
+[Renderer options](/guides/serialization/rendering.html).
+
+## Rendering resources
+
+```ruby
+class PostsController < ActionController::Base
+  # ...
+
+  def index
+    render jsonapi: Posts.all, include: [:author, comments: [:author]],
+           fields: { users: [:name, :email],
+                     posts: [:title, :content] }
+  end
+
+  # ...
+end
+```
+
+## Rendering relationships
+
+```ruby
+class PostsController < ActionController::Base
+  # ...
+
+  def comments_relationship
+    post = Post.find(id: params[:id])
+    render jsonapi: post, relationship: :comments,
+           include: [comments: [:author]],
+           fields: { users: [:name, :email],
+                     posts: [:title, :content] }
+  end
+
+  # ...
+end
+```
+
+## Rendering errors
+
+```ruby
+class PostsController < ActionController::Base
+  # ...
+
+  def create
+    post = Post.new(params[:post])
+
+    if post.save
+      render jsonapi: post
+    else
+      render jsonapi_errors: post.errors
+    end
+  end
+
+  # ...
+end
+```
+
+## Configuration
+
+### Application-wide settings
+
+You can customize default behaviors in an initializer (`$ rails generate jsonapi:initializer`).
+
+### Controller-wide settings
+
+It is also possible to override application-wide settings at controller level. Simply define
+one of the available hooks:
+`jsonapi_class`, `jsonapi_errors_class`,`jsonapi_object`, `jsonapi_include`,
+`jsonapi_fields`, `jsonapi_expose`, `jsonapi_pagination`.
+
+### Action-wide settings
+
+It is always possible to override the application/controller-wide settings at action level
+by providing the relevant [renderer options](/guides/serialization/rendering.html).
+
+### Serializable class lookup
+
+By default, for an instance of `Article`, the corresponding serializable resource class
+will be guessed as `SerializableArticle`.
+
+This behavior is customizable by overriding the `jsonapi_class` setting (or by supplying
+a `class` renderer option). Either set it to an explicit hash, or a hash with a dynamic
+default value for inferrence.
+
+### Pagination
+
+TODO

source/guides/index.html.md

@@ -35,5 +35,6 @@ generators,
 These guides should get you up to speed with using jsonapi-rb. If you have more
 questions, feel free to drop by on [Gitter](http://gitter.im/jsonapi-rb).
 
++ [Getting started](/guides/getting_started)
 + [Serialization](/guides/serialization)
 + [Deserialization](/guides/deserialization)

source/guides/serialization/defining.html.md

@@ -221,37 +221,6 @@ By default, for an instance of class `Post`, the corresponding serializable
 resource class will be assumed to be `SerializablePost` (this behavior can be
 configured, see next section).
 
-In case you want to explicitly set the serializable resource class that will be
-used for the related resources, you can specify it via the `class` option. Its
-value can be either a constant:
-
-```ruby
-class SerializablePost < JSONAPI::Serializable::Resource
-  # ...
-  has_many :comments, class: New::SerializableComment
-end
-```
-a string:
-
-```ruby
-class SerializablePost < JSONAPI::Serializable::Resource
-  # ...
-  has_many :comments, class: 'New::SerializableComment'
-end
-```
-or a hash (for polymorphic relationships):
-
-```ruby
-class SerializablePost < JSONAPI::Serializable::Resource
-  # ...
-  has_one :author, class: { User: 'SpecialSerializableUser',
-                            Admin: 'SpecialSerializableAdmin' }
-end
-```
-
-Note that while this usage is supported, it is actually recommended to set a
-global explicit mapping at the renderer level.
-
 ### Linkage data overriding
 
 Note: it is also possible to manually override the linkage data for a

source/guides/serialization/rendering.html.md

@@ -7,108 +7,28 @@ The renderer takes your business objects (which can be any ruby objects: POROs,
 ActiveRecord models, or even plain hashes), along with some optional parameters
 (`include`, `fields`, etc.), and builds the JSON API document.
 
-## Plain ruby
+The available global options are:
 
-When using jsonapi-rb in plain ruby (or from within a framework outside of a
-controller), you can render a document as follows:
-
-```ruby
-JSONAPI::Serializable::SuccessRenderer.render(posts)
-```
-
-You can also pass options to the renderer:
-
-```ruby
-JSONAPI::Serializable::SuccessRenderer.render(posts,
-                                             include: [:author, comments: [:author]],
-                                             fields:  { users: [:name, :email],
-                                                        posts: [:title, :content] })
-```
-
-For a comprehensive list of renderer options, see [Renderer options]().
-
-## Ruby on Rails
-
-When using jsonapi-rb with Rails (via the jsonapi-rails gem), rendering is done
-via the usual `render` controller method:
-
-```ruby
-render jsonapi: posts
-```
-and options are passed as named arguments:
-
-```ruby
-render jsonapi: posts,
-       include: [:author, comments: [:author]],
-       fields:  { users: [:name, :email],
-                  posts: [:title, :content] }
-```
-
-For a comprehensive list of renderer options, see [Renderer options]().
-
-## Hanami
-
-When using jsonapi-rb with Hanami (via the jsonapi-hanami gem), enabling of
-jsonapi-rb features is opt-in, and is done by including
-`JSONAPI::Hanami::Action` in your actions.
-Rendering is done by setting options directly on the controller action instance.
-The primary data is set via the `self.data` setter.
-
-Exposures are available from within the `SerializableResource` class as instance
-variables.
-
-Example:
-
-```ruby
-module API::Controllers::Posts
-  class Create
-    include API::Action
-    include JSONAPI::Hanami::Action
-
-    expose :url_helpers
-
-    def call(params)
-      # ...
-      @url_helpers = routes  # Will be available inside serializable resources.
-
-      self.data = posts
-      self.include = [:author, comments: [:author]]
-      self.fields  = { users: [:name, :email],
-                       posts: [:title, :content] }
-    end
-  end
-end
-```
-
-For a comprehensive list of renderer options, see [Renderer options]().
-
-## Renderer options
-
-The available options are:
-
-+ data-related options:
-  + `include`: the related resources to include in the document. This option can
-    be specified as a string (e.g. `"author,comments.author"`), or as an array/
-    hash of symbols (e.g. `[:author, comments: [:author]]`).
-  + `fields`: a restricted set of fields for some or all resources. This option
-    can be specified as a hash of arrays of symbols (e.g.
-    `{ users: [:name, :email], posts: [:title, :content] }`).
-  + `expose`: a hash of arbitrary variables that will be made available to the
-    serializable resources as instance variables.
 + serializable resource class related options:
-  + `inferrer`: a hash globally mapping model class names to serializable resource
-    class names.
-  + `namespace`: the namespace in which to look for serializable resource
-    classes. This option can be specified as a constant (e.g. `V2`), or as a
-    string (e.g. `"V2"`).
-  + `class`: the serializable resource class(es) to be used for the primary
-    data. This option can be specified as a constant (e.g. `SerializablePost`),
-    as a string (e.g. `"SerializablePost"`), or as a hash (e.g.
-    `{ Article: "SerializableFormattedArticle", Letter: "SerializableFormattedLetter" }`).
+  + `class`: a hash globally mapping model class names to serializable resource
+     class names.
 + top level properties:
   + `links`: a set of top level links. This option can be specified as a hash.
   + `meta`: top level meta information. This option can be specified as a hash.
   + `jsonapi`: top level `jsonapi` object. This option can be specified as a
     hash.
 + framework-specific options: in Hanami and Rails, the usual options such as
 `status` are respected.
+
+When serializing resources and relationships, the following
+data-related options are also available:
+
++ `include`: the related resources to include in the document. This option can
+  be specified as a string (e.g. `"author,comments.author"`), or as an array/
+  hash of symbols (e.g. `[:author, comments: [:author]]`).
++ `fields`: a restricted set of fields for some or all resources. This option
+  can be specified as a hash of arrays of symbols (e.g.
+  `{ users: [:name, :email], posts: [:title, :content] }`).
++ `expose`: a hash of arbitrary variables that will be made available to the
+  serializable resources as instance variables.
++ `cache`: a cache supporting `fetch_multi` for fragment caching.