Initial commit of the new docs

Gemfile

@@ -0,0 +1,9 @@
+source "http://rubygems.org"
+
+gem 'nanoc'
+gem 'adsf'
+gem 'fssm'
+gem 'kramdown'
+gem 'coderay'
+gem 'pygments.rb'
+gem 'nokogiri'

Gemfile.lock

@@ -0,0 +1,32 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    adsf (1.1.1)
+      rack (>= 1.0.0)
+    coderay (1.0.8)
+    colored (1.2)
+    cri (2.3.0)
+      colored (>= 1.2)
+    fssm (0.2.9)
+    kramdown (0.14.0)
+    nanoc (3.4.2)
+      cri (~> 2.2)
+    nokogiri (1.4.7)
+    posix-spawn (0.3.6)
+    pygments.rb (0.3.2)
+      posix-spawn (~> 0.3.6)
+      yajl-ruby (~> 1.1.0)
+    rack (1.4.1)
+    yajl-ruby (1.1.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  adsf
+  coderay
+  fssm
+  kramdown
+  nanoc
+  nokogiri
+  pygments.rb

Rules

@@ -0,0 +1,45 @@
+#!/usr/bin/env ruby
+
+# A few helpful tips about the Rules file:
+#
+# * The string given to #compile and #route are matching patterns for
+#   identifiers--not for paths. Therefore, you can’t match on extension.
+#
+# * The order of rules is important: for each item, only the first matching
+#   rule is applied.
+#
+# * Item identifiers start and end with a slash (e.g. “/about/” for the file
+#   “content/about.html”). To select all children, grandchildren, … of an
+#   item, use the pattern “/about/*/”; “/about/*” will also select the parent,
+#   because “*” matches zero or more characters.
+
+compile '/static/*' do
+end
+
+compile '*' do
+  if item.binary?
+    # don’t filter binary items
+  else
+    filter :erb
+    filter :kramdown
+    filter :colorize_syntax,
+           :colorizers => {:javascript => :pygmentsrb}
+    layout 'default'
+  end
+end
+
+route '/static/*' do
+  '/assets'+item.identifier[7..-2]
+end
+
+route '*' do
+  if item.binary?
+    # Write item with identifier /foo/ to /foo.ext
+    item.identifier.chop + '.' + item[:extension]
+  else
+    # Write item with identifier /foo/ to /foo/index.html
+    item.identifier + 'index.html'
+  end
+end
+
+layout '*', :erb

config.yaml

@@ -0,0 +1,81 @@
+# A list of file extensions that nanoc will consider to be textual rather than
+# binary. If an item with an extension not in this list is found,  the file
+# will be considered as binary.
+text_extensions: [ 'coffee', 'css', 'erb', 'haml', 'handlebars', 'hb', 'htm', 'html', 'js', 'less', 'markdown', 'md', 'ms', 'mustache', 'php', 'rb', 'sass', 'scss', 'txt', 'xhtml', 'xml' ]
+
+# The path to the directory where all generated files will be written to. This
+# can be an absolute path starting with a slash, but it can also be path
+# relative to the site directory.
+output_dir: output
+
+# A list of index filenames, i.e. names of files that will be served by a web
+# server when a directory is requested. Usually, index files are named
+# “index.html”, but depending on the web server, this may be something else,
+# such as “default.htm”. This list is used by nanoc to generate pretty URLs.
+index_filenames: [ 'index.html' ]
+
+# Whether or not to generate a diff of the compiled content when compiling a
+# site. The diff will contain the differences between the compiled content
+# before and after the last site compilation.
+enable_output_diff: false
+
+prune:
+  # Whether to automatically remove files not managed by nanoc from the output
+  # directory. For safety reasons, this is turned off by default.
+  auto_prune: false
+
+  # Which files and directories you want to exclude from pruning. If you version
+  # your output directory, you should probably exclude VCS directories such as
+  # .git, .svn etc.
+  exclude: [ '.git', '.hg', '.svn', 'CVS' ]
+
+# The data sources where nanoc loads its data from. This is an array of
+# hashes; each array element represents a single data source. By default,
+# there is only a single data source that reads data from the “content/” and
+# “layout/” directories in the site directory.
+data_sources:
+  -
+    # The type is the identifier of the data source. By default, this will be
+    # `filesystem_unified`.
+    type: filesystem_unified
+
+    # The path where items should be mounted (comparable to mount points in
+    # Unix-like systems). This is “/” by default, meaning that items will have
+    # “/” prefixed to their identifiers. If the items root were “/en/”
+    # instead, an item at content/about.html would have an identifier of
+    # “/en/about/” instead of just “/about/”.
+    items_root: /
+
+    # The path where layouts should be mounted. The layouts root behaves the
+    # same as the items root, but applies to layouts rather than items.
+    layouts_root: /
+
+    # Whether to allow periods in identifiers. When turned off, everything
+    # past the first period is considered to be the extension, and when
+    # turned on, only the characters past the last period are considered to
+    # be the extension. For example,  a file named “content/about.html.erb”
+    # will have the identifier “/about/” when turned off, but when turned on
+    # it will become “/about.html/” instead.
+    allow_periods_in_identifiers: false
+
+  -
+    type: static
+    items_root: /static
+
+# Configuration for the “watch” command, which watches a site for changes and
+# recompiles if necessary.
+watcher:
+  # A list of directories to watch for changes. When editing this, make sure
+  # that the “output/” and “tmp/” directories are _not_ included in this list,
+  # because recompiling the site will cause these directories to change, which
+  # will cause the site to be recompiled, which will cause these directories
+  # to change, which will cause the site to be recompiled again, and so on.
+  dirs_to_watch: [ 'content', 'layouts', 'lib' ]
+
+  # A list of single files to watch for changes. As mentioned above, don’t put
+  # any files from the “output/” or “tmp/” directories in here.
+  files_to_watch: [ 'config.yaml', 'Rules' ]
+
+  # When to send notifications (using Growl or notify-send).
+  notify_on_compilation_success: true
+  notify_on_compilation_failure: true

content/docs/authentication/flows/app-access-token.md

@@ -0,0 +1,21 @@
+# App Access Token Flow
+
+The App Access Token Flow is used to request a token that is tied to your application instead of a specific user. **App access tokens cannot be distributed and must only be used from a server. You should consider them secret.** If you would like a client (i.e. mobile) application to use an app access token, that app must connect to a server you control that stores the app access token.
+
+To retrieve an app access token, your app must make the following request:
+
+    POST https://alpha.app.net/oauth/access_token
+
+with URL-encoded POST body:
+
+        client_id=[your client ID]
+        &client_secret=[your client secret]
+        &grant_type=client_credentials
+
+> Note: we also accept the `client_id` and `client_secret` parameters via the Authorization header, as described in [section 2.3.1 of the spec](http://tools.ietf.org/html/draft-ietf-oauth-v2-31#section-2.3.1).
+
+App.net will respond with a JSON-encoded token:
+
+    {"access_token": "[app access token]"}
+
+You can use this access_token to make authenticated calls to the App.net API on behalf of your app.

content/docs/authentication/flows/password.md

@@ -0,0 +1,55 @@
+# Password Flow
+
+This is referred to as the Resource Owner Password Credential flow in the OAuth 2.0 spec. However, in order to protect the integrity of `client_secret`s, we require the use of a separate token to be included with flows.
+
+This flow is useful for obtaining an access token authorized for specific scopes when pushing the user into a browser-based flow is impractical for technical or user-experience reasons.
+
+## Important notes
+
+**Security of user accounts is the most important thing.** When in doubt, err on the side of securing user password information, rather than optimizing for user experience.
+
+**Your application must be specifically approved to use this flow.** To obtain authorization, please email password-auth@app.net from your user account's email address and include your application's `client_id`, your username, and an explanation of your situation.
+
+## Additional rules
+
+> Some of these rules might limit what you can do with your app. Please do not attempt to circumvent them, or we will disable your application token. That may sound harsh, but it is of utmost importance that we protect the integrity of the service and the security of user accounts.
+
+1. **NEVER** store user password information, no matter how securely. Users should be able to disable access to your application at any time by revoking authorization. Access tokens are designed not to expire unless users take explicit action, so there is no need to build in a mechanism to reauthenticate that would require storing passwords.
+1. Do not send user password information over the network, except to the prescribed App.net OAuth endpoint.
+1. **NEVER** log user password information, even debug logging to your app or device's console. It is too easy to accidentally leak password information this way.
+1. These flows should only be used in cases where browser-based authentication is impractical. For one-off applications, shell scripts, please use the pre-generated access token available in the "Apps" section of App.net.
+1. Users must have a way to see which scopes are being requested by an application. This can be behind a "more info" button, but must at least be exposed on the login screen, before users are required to enter their password information to coninue.
+1. By default, **users will receive an email each time they authorize an application with this flow**, listing the name of the application, the scopes requested and the time that authorization was performed.
+1. If an error is returned from the OAuth endpoint, it MUST be displayed to users verbatim.
+1. If these rules are updated, application developers must make reasonable attempts to comply with new regulations wherever possible.
+
+## Procedure
+
+Once approved, it's pretty straightforward:
+
+1. From your client, make a request to the token endpoint:
+
+        POST https://alpha.app.net/oauth/access_token
+
+    with URL-encoded POST body:
+
+         client_id=[your client ID]
+        &password_grant_secret=[your password grant secret, not your client secret]
+        &grant_type=password
+        &username=[user's email or username]
+        &password=[user's password]
+        &scope=[scopes separated by spaces]
+
+    > Note: The use of `password_grant_secret` diverges from the OAuth 2.0 specificaion. `password_grant_secret` is a special token that we'll send you when your use of the password flow is approved.
+
+1. If the authorization was successful, App.net will respond with a JSON-encoded token:
+
+        {"access_token": "[user access token]"}
+
+    You can use this access_token to make authenticated calls to the App.net API on behalf of a user.
+
+1. If authentication failed or there was another error, App.net will respond with an error:
+
+        {"error": "Authentication failed"}
+
+    If the `error_text` key is present in this dictionary, you **MUST** show a modal dialog or equivalent containing this text. If possible, you should include value of the `error_title` key as a title in your dialog.

content/docs/authentication/flows/web.md

@@ -0,0 +1,66 @@
+# Web Flows 
+
+## Server-side Flow
+
+This is the easiest way to get an access token—we recommend it to most users of the API. If you're writing an app on a server using a language like  Ruby, Python, PHP, Java, etc. you should use this flow.
+
+**You must keep your client_secret confidential**. That means that you may not include it in the source code or binary of an application that you ship to end-users, even in obscured form. 
+
+1. Direct the user that you want to authenticate to this URL:
+
+        https://alpha.app.net/oauth/authenticate
+            ?client_id=[your client ID]
+            &response_type=code
+            &redirect_uri=[your redirect URI]
+            &scope=[scopes separated by spaces]
+
+    > To avoid cross-site scripting attacks, we also support the **state** parameter. If you include a state parameter, we will append it to the query parameters when redirecting the user to your **Redirection URI**.
+
+    > To comply with Apple's App Store Guidelines, you can add the query string parameter `adnview=appstore` to hide all signup links on the authentication pages.
+
+    We'll request that the user log in to App.net and show them a permissions dialog allowing them to choose whether to authorize your application.
+
+1. If the user decides to authorize your application, they will be redirected to: `https://[your registered redirect URI]/?code=CODE`
+
+    > If you included a query string in your redirect URI, the `code` parameter will be appended. Likewise, the scheme of your redirect URI will be respected, though we strongly recommend sending all traffic over HTTPS.
+
+1. On your server, your application should then make the following request: `POST https://alpha.app.net/oauth/access_token`
+
+    with URL-encoded POST body:
+
+        client_id=[your client ID]
+        &client_secret=[your client secret]
+        &grant_type=authorization_code
+        &redirect_uri=[your registered redirect URI]
+        &code=[code received from redirect URI]
+
+    > Note: we also accept the `client_id` and `client_secret` parameters via the Authorization header, as described in [section 2.3.1 of the spec](http://tools.ietf.org/html/draft-ietf-oauth-v2-31#section-2.3.1).
+
+1. App.net will respond with a JSON-encoded token: `{"access_token": "[user access token]"}`
+
+    You can use this access_token to make authenticated calls to the App.net API on behalf of a user.
+
+## Client-side Flow
+
+If you're building a client-side Javascript app or a mobile app that doesn't have an associated back-end server, you'll find that you need to take some special steps to keep your `client_secret` confidential.
+
+1. Direct the user that you want to authenticate to this URL:
+
+        https://alpha.app.net/oauth/authenticate
+            ?client_id=[your client ID]
+            &response_type=token
+            &redirect_uri=[your redirect URI]
+            &scope=[scopes separated by spaces]
+
+    > To avoid cross-site scripting attacks, we also support the **state** parameter. If you include a state parameter, we will append it to the query parameters when redirecting the user to your **Redirection URI**.
+
+    > To comply with Apple's App Store Guidelines, you can add the query string parameter `adnview=appstore` to hide all signup links on the authentication pages.
+
+    We'll request that the user log in to App.net and show them a permissions dialog allowing them to choose whether to authorize your application.
+
+1. If the user decides to authorize your application, they will be redirected to: `https://[your registered redirect URI]/#access_token=[user access token]`
+
+    > If you included a query string in your redirect URI, the `code` parameter will be appended. Likewise, the scheme of your redirect URI will be respected, though we strongly recommend sending all traffic over HTTPS.
+
+    The access_token will be appended to the URI in the fragment section, encoded as if it were a query string. Your client-side code should parse this for the access_token.
+