Setup docs

Gemfile

@@ -8,6 +8,7 @@ gem 'unicorn'
 
 gem 'tent-schemas', :git => 'git://github.com/tent/tent-schemas.git'
 gem 'yajl-ruby'
+gem 'redcarpet'
 
 # Custom Boostrap 3
 gem 'fly', :git => 'git://github.com/tent/fly.git', :branch => 'master'

Gemfile.lock

@@ -101,6 +101,7 @@ GEM
       ffi (>= 0.5.0)
     rb-kqueue (0.2.0)
       ffi (>= 0.5.0)
+    redcarpet (2.2.2)
     sass (3.2.10)
     sprockets (2.10.0)
       hike (~> 1.2)
@@ -134,6 +135,7 @@ DEPENDENCIES
   middleman-blog (~> 3.2.0)
   middleman-livereload (~> 3.1.0)
   middleman-more (~> 3.1.3)
+  redcarpet
   tent-schemas!
   unicorn
   yajl-ruby

config.rb

@@ -30,6 +30,17 @@
 
 set :images_dir, 'images'
 
+set :markdown_engine, :redcarpet
+set :markdown,
+      fenced_code_blocks: true,
+      no_intra_emphasis: true,
+      autolink: true,
+      tables: true,
+      strikethrough: true,
+      lax_html_blocks: true,
+      space_after_headers: true,
+      superscript: true
+
 # Configure Sprockets
 require 'fly'
 Fly::Sprockets.setup(sprockets)

lib/tent_doc.rb

@@ -1,17 +1,27 @@
 require 'tent_doc/schema_table'
 require 'tent_doc/api_example'
+require 'middleman-core/renderers/redcarpet'
 
-module TentDoc
-  PROCESSORS = {
-    :schema_table => SchemaTable,
-    :api_example => APIExample
-  }.freeze
+# Piggyback on Middleman's markdown renderer
+module Middleman
+  module Renderers
+    class RedcarpetTemplate
+      PROCESSORS = {
+        :schema_table => ::TentDoc::SchemaTable,
+        :api_example => ::TentDoc::APIExample
+      }.freeze
 
-  def self.compile(data, options = {})
-    PROCESSORS.inject(data) do |data, (key, processor)|
-      processor.compile(data, options[key] || {})
+      alias _evaluate evaluate
+      def evaluate(scope, locals, &block)
+        _output = data
+        _output = PROCESSORS.inject(_output) do |memo, (key, processor)|
+          processor.compile(memo.to_s, options[key] || {}) || memo
+        end
+
+        @data = _output
+
+        _evaluate(scope, locals, &block)
+      end
     end
   end
 end
-
-::Tilt.register(TentDoc, 'tent_doc')

lib/tent_doc/api_example.rb

@@ -7,7 +7,7 @@ def self.compile(data, options = {})
     end
 
     DEFAULT_OPTIONS = {
-      :path => File.expand_path("../../../content/docs/api_examples.json", __FILE__)
+      :path => File.expand_path("../../../source/docs/api_examples.json", __FILE__)
     }.freeze
 
     attr_reader :data, :options

lib/tent_doc/schema_table.rb

@@ -34,7 +34,8 @@ def initialize(data, options = {})
     end
 
     def compile
-      data.gsub(/\{([\w-]+) schema\}/) { schema_table($1) }
+      reg = /\{([\w-]+) schema\}/
+      data.gsub(reg) { |m| m.match(reg); schema_table($1) }
     end
 
     def load_schema(schema_name)

lib/tent_doc/schema_table/html_element.rb

@@ -8,7 +8,7 @@ def initialize(name, content = '', attributes = {})
       end
 
       def <<(content)
-        self.content << content
+        self.content << content.to_s
       end
 
       def to_html
@@ -22,6 +22,10 @@ def to_html
 
         %(<#{name}#{attrs}>\n#{content}\n</#{name}>\n)
       end
+
+      def to_s
+        to_html
+      end
     end
   end
 end

source/docs/api.html.md

@@ -0,0 +1,136 @@
+---
+title: API Endpoints
+---
+
+## Concepts
+
+### Pagination
+
+All post lists (feed, versions, children, mentions) support pagination. The
+response to a list request contains a set of links to other pages. These links
+are just the query part of the URL ("?" followed by zero or more query
+parameters) and contain all filtering and limiting parameters specified in the
+request plus additional/updated parameters that specify a page. Links to the
+current page and pages that do not exist are omitted.
+
+```json
+{
+  "pages": {
+    "first": "?page=1",
+    "prev": "?page=1",
+    "next": "?page=2",
+    "last": "?page=4"
+  }
+}
+```
+
+### Response Envelope
+
+{data schema}
+
+## new_post
+
+{new_post example}
+
+### Attachments
+
+{new_multipart_post example}
+
+## posts_feed
+
+### Sorting
+
+The feed is sorted in descending order by timestamp. The timestamp used to sort
+is specified with the `sort_by` parameter, and defaults to `received_at`. The
+most recent version of each post is shown, as determined by sorting the
+versions with the version timestamp equivalent to the one specified in
+`sort_by`. For example if `sort_by` is `received_at`, the version shown is the
+most recent as sorted by `version.received_at`. When there are duplicate
+timestamps, the natural byte order of the version identifier is used to maintain
+a deterministic sort.
+
+### Parameters
+
+| Parameter | Value |  Description |
+| --------- | ----- | ------------ |
+| `limit` | Integer | The maximum number of posts to return. Defaults to `25`. |
+| `max_refs` | Integer | The maximum number of refs to return per post. Defaults to `0`. |
+| `sort_by` | String | Specifies the sort order. One of `received_at`, `published_at`, `version.received_at` or `version.published_at`. Defaults to `received_at`. |
+| `since` | String | Requests posts published after the specified timestamp. The last post on the page is the first post published after the specified timestamp. The timestamp is in milliseconds since the Unix epoch, and may be optionally followed by a space and a post version. |
+| `until` | String | Requests posts published after the specified timestamp. The first post on the page is the most recent post published. Must not be combined with `since`. The timestamp is in milliseconds since the Unix epoch, and may be optionally followed by a space and a post version. |
+| `before` | String | Requests posts published before the specified timestamp. The first post on the page is the most recent post published before the specified timestamp unless combined with `since`. The timestamp is in milliseconds since the Unix epoch, and may be optionally followed by a space and a post version. |
+| `types` | String | Limits posts by comma-separated post types. Types with no fragment match all posts of the specified base type. |
+| `entities` | String | Selects posts published by one or more comma-separated entities. |
+| `mentions` | String | Selects posts that mention specified entities and posts. One or more comma-separated mentions may be specified. Each mention is a entity url optionally followed by a space and a post ID. Multiple `mentions` parameters may be specified. |
+
+[**Pagination Diagram**](<%= asset_path('tent_pagination.png') %>)
+
+### Examples
+
+{posts_feed example}
+
+#### Refs
+
+{posts_feed_refs example}
+
+#### Conditional Request
+
+{posts_feed_304 example}
+
+#### HEAD Request (Count)
+
+{posts_feed_count example}
+
+## post
+
+### Create New Version
+
+{new_post_version example}
+
+### Get (with refs)
+
+{post_refs example}
+
+### Mentions
+
+{post_mentions example}
+
+#### HEAD (Count)
+
+{post_mentions_count example}
+
+### Versions
+
+{post_versions example}
+
+#### HEAD (Count)
+
+{post_versions_count example}
+
+### Child Versions
+
+{post_children example}
+
+#### HEAD (Count)
+
+{post_children_count example}
+
+## attachment
+
+{get_attachment example}
+
+## post_attachment
+
+{get_post_attachment example}
+
+## batch
+
+## server_info
+
+## oauth_auth
+
+{oauth_redirect example}
+
+## oauth_token
+
+{oauth_token example}

source/docs/apps.html.md

@@ -0,0 +1,63 @@
+---
+title: Apps
+---
+
+Apps allow users to interact with data in Tent. [OAuth
+2.0](https://tools.ietf.org/html/rfc6749) combined with the [Hawk authentication
+scheme](/docs/authentication) are used for authorization and authentication.
+
+## Discovery
+
+Typically an entity will provide the app with their Entity URL when logging in.
+[Discovery](/docs/servers-entities#discovery) must be performed on the URL in
+order to get the meta post with the list of servers and endpoints necessary to
+talk to the Tent servers that represent the entity.
+
+{discover_head example}
+
+{discover_meta example}
+
+## Registration
+
+Before going through the OAuth Authorization Grant flow for the first time, the
+app must be registered. Registration is the process of creating an app post
+using the `new_post` endpoint. The app post contains all of the metadata that
+the server needs from the app.
+
+{app_create example}
+
+The response to the post creation request will include a `Link` header that
+contains a link to the credentials for the app. The credentials are used in the
+*Access Token Request*.
+
+{app_credentials example}
+
+## OAuth
+
+The `oauth_auth` and `oauth_token` endpoints are utilized for the OAuth
+*Authorization Request* and the *Access Token Request* respectively. Tent
+implements a subset of OAuth 2.0 that only supports the Authorization Code grant
+type. The authorization code is exchanged for the authorization's Hawk
+credentials.
+
+To authorize the app, redirect the user to the `oauth_auth` endpoint with the
+`client_id` URL parameter set to the `id` field from the previously created app
+post. If the app is web-based, the `state` parameter should also be set to
+a random value to be verified when the user is redirected back.
+
+{oauth_redirect example}
+
+After the user authorizes the application, the server will redirect to the app's
+`redirect_uri` provided in the initial registration. The redirect URL will
+include a `code` parameter and the `state` parameter if provided in the initial
+redirect. The `code` is then traded by the application for authorized
+credentials that may be used to interact with the server. The `access_token` is
+used as the ID in Hawk signatures.
+
+{oauth_token example}
+
+### App Registration Schema
+
+{post_app schema}
+
+## Notifications