Move docs into master

.gitignore

@@ -1,5 +1,6 @@
 .DS_Store
 build
 composer.lock
+docs/_site
 phpunit.xml
 vendor

docs/Gemfile

@@ -0,0 +1,2 @@
+source 'https://rubygems.org'
+gem 'github-pages'

docs/Gemfile.lock

@@ -0,0 +1,126 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    RedCloth (4.2.9)
+    activesupport (4.2.0)
+      i18n (~> 0.7)
+      json (~> 1.7, >= 1.7.7)
+      minitest (~> 5.1)
+      thread_safe (~> 0.3, >= 0.3.4)
+      tzinfo (~> 1.1)
+    blankslate (2.1.2.4)
+    celluloid (0.16.0)
+      timers (~> 4.0.0)
+    classifier-reborn (2.0.2)
+      fast-stemmer (~> 1.0)
+    coffee-script (2.3.0)
+      coffee-script-source
+      execjs
+    coffee-script-source (1.8.0)
+    colorator (0.1)
+    execjs (2.2.2)
+    fast-stemmer (1.0.2)
+    ffi (1.9.6)
+    gemoji (2.1.0)
+    github-pages (31)
+      RedCloth (= 4.2.9)
+      github-pages-health-check (~> 0.2)
+      jekyll (= 2.4.0)
+      jekyll-coffeescript (= 1.0.1)
+      jekyll-mentions (= 0.2.1)
+      jekyll-redirect-from (= 0.6.2)
+      jekyll-sass-converter (= 1.2.0)
+      jekyll-sitemap (= 0.6.3)
+      jemoji (= 0.4.0)
+      kramdown (= 1.3.1)
+      liquid (= 2.6.1)
+      maruku (= 0.7.0)
+      mercenary (~> 0.3)
+      pygments.rb (= 0.6.0)
+      rdiscount (= 2.1.7)
+      redcarpet (= 3.1.2)
+      terminal-table (~> 1.4)
+    github-pages-health-check (0.2.1)
+      net-dns (~> 0.6)
+      public_suffix (~> 1.4)
+    hitimes (1.2.2)
+    html-pipeline (1.9.0)
+      activesupport (>= 2)
+      nokogiri (~> 1.4)
+    i18n (0.7.0)
+    jekyll (2.4.0)
+      classifier-reborn (~> 2.0)
+      colorator (~> 0.1)
+      jekyll-coffeescript (~> 1.0)
+      jekyll-gist (~> 1.0)
+      jekyll-paginate (~> 1.0)
+      jekyll-sass-converter (~> 1.0)
+      jekyll-watch (~> 1.1)
+      kramdown (~> 1.3)
+      liquid (~> 2.6.1)
+      mercenary (~> 0.3.3)
+      pygments.rb (~> 0.6.0)
+      redcarpet (~> 3.1)
+      safe_yaml (~> 1.0)
+      toml (~> 0.1.0)
+    jekyll-coffeescript (1.0.1)
+      coffee-script (~> 2.2)
+    jekyll-gist (1.1.0)
+    jekyll-mentions (0.2.1)
+      html-pipeline (~> 1.9.0)
+      jekyll (~> 2.0)
+    jekyll-paginate (1.1.0)
+    jekyll-redirect-from (0.6.2)
+      jekyll (~> 2.0)
+    jekyll-sass-converter (1.2.0)
+      sass (~> 3.2)
+    jekyll-sitemap (0.6.3)
+    jekyll-watch (1.2.0)
+      listen (~> 2.7)
+    jemoji (0.4.0)
+      gemoji (~> 2.0)
+      html-pipeline (~> 1.9)
+      jekyll (~> 2.0)
+    json (1.8.1)
+    kramdown (1.3.1)
+    liquid (2.6.1)
+    listen (2.8.4)
+      celluloid (>= 0.15.2)
+      rb-fsevent (>= 0.9.3)
+      rb-inotify (>= 0.9)
+    maruku (0.7.0)
+    mercenary (0.3.5)
+    mini_portile (0.6.1)
+    minitest (5.5.0)
+    net-dns (0.8.0)
+    nokogiri (1.6.5)
+      mini_portile (~> 0.6.0)
+    parslet (1.5.0)
+      blankslate (~> 2.0)
+    posix-spawn (0.3.9)
+    public_suffix (1.4.6)
+    pygments.rb (0.6.0)
+      posix-spawn (~> 0.3.6)
+      yajl-ruby (~> 1.1.0)
+    rb-fsevent (0.9.4)
+    rb-inotify (0.9.5)
+      ffi (>= 0.5.0)
+    rdiscount (2.1.7)
+    redcarpet (3.1.2)
+    safe_yaml (1.0.4)
+    sass (3.4.9)
+    terminal-table (1.4.5)
+    thread_safe (0.3.4)
+    timers (4.0.1)
+      hitimes
+    toml (0.1.2)
+      parslet (~> 1.5.0)
+    tzinfo (1.2.2)
+      thread_safe (~> 0.1)
+    yajl-ruby (1.1.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  github-pages

docs/README.md

@@ -0,0 +1,12 @@
+# Spotify Web API PHP docs
+
+To build these docs, follow [these steps](http://jekyllrb.com/docs/github-pages/) to get Jekyll up and running.
+
+When done, clone [this repo](https://github.com/jwilsson/phpdoc-md) and then run these commands:
+
+```
+phpdoc -d /spotify-web-api-php-master/src -t . --template="xml" --ignore "*Exception.php" --visibility=public
+phpdocmd structure.xml /spotify-web-api-php/method-reference
+```
+
+Change paths etc. as necessary, of course.

docs/_config.yml

@@ -0,0 +1,5 @@
+name: "spotify-web-api-php"
+description: "A PHP implementation of Spotify's Web API."
+
+baseurl: /spotify-web-api-php
+encoding: utf-8

docs/_layouts/default.html

@@ -0,0 +1,55 @@
+<!DOCTYPE html>
+
+<head>
+    <meta charset="utf-8">
+    <meta name="description" content="{{ site.description }}">
+    <title>{{ page.title }} | {{ site.name }}</title>
+    <link rel="stylesheet" href="{{ site.baseurl }}/css/style.css">
+</head>
+
+<body>
+
+    <header class="main-header">
+
+        <div class="wrapper">
+
+            <a class="forkme-banner" href="https://github.com/jwilsson/spotify-web-api-php/">View on GitHub</a>
+
+            <h1 class="project-title"><a href="{{ site.baseurl }}/">{{ site.name }}</a></h1>
+            <h2 class="project-tagline">{{ site.description }}</h2>
+
+            <div class="downloads">
+
+                <a class="zip-download-link" href="https://github.com/jwilsson/spotify-web-api-php/archive/master.zip">Download as a .zip file</a>
+                <a class="tar-download-link" href="https://github.com/jwilsson/spotify-web-api-php/archive/master.tar.gz">Download as a tar.gz file</a>
+
+            </div>
+
+        </div>
+
+    </header>
+
+    <main class="main-content">
+
+        <div class="wrapper">
+
+            <h2>{{ page.title }}</h2>
+
+            {{ content }}
+
+        </div>
+
+    </main>
+
+    <footer class="main-footer">
+
+        <div class="wrapper">
+
+            <p class="copyright">Spotify-web-api-php maintained by <a href="https://github.com/jwilsson">jwilsson</a></p>
+            <p class="copyright">Slate theme by <a href="https://github.com/jsncostello">Jason Costello</a></p>
+
+        </div>
+
+    </footer>
+
+</body>

docs/authorization.md

@@ -0,0 +1,109 @@
+---
+layout: default
+title: Authorization
+---
+
+Some API methods require authorization. Before using these methods you'll need to create an app at [Spotify's developer site](https://developer.spotify.com).
+Authorization can also be used to increase the rate limit of your API calls, the [Client Credentials Flow](#client-credentials-flow) is best suited for this scenario.
+
+There are a few different ways to authenticate a user, `spotify-web-api-php` supports two of these.
+
+*Note: All examples assume the use of Composer or a autoloader.*
+
+### Authorization Code Flow
+This method requires some interaction from the user but in turn allows access to user information.
+
+#### Step 1
+
+There are two steps required to authenticate the user. The first step is to request permissions (known as **scopes**) from the user and redirecting to the authorize URL.
+
+
+    require 'vendor/autoload.php';
+
+    $session = new SpotifyWebAPI\Session('CLIENT_ID', 'CLIENT_SECRET', 'REDIRECT_URI');
+
+    $scopes = array(
+        'playlist-read-private',
+        'user-read-private'
+    );
+
+    $authorizeUrl = $session->getAuthorizeUrl(array(
+        'scope' => $scopes
+    ));
+
+    header('Location: ' . $authorizeUrl);
+    die();
+
+
+To read more about **scopes**, please refer to the [Spotify documentation](https://developer.spotify.com/web-api/using-scopes/).
+To see the other available options for `getAuthorizeUrl()`, refer to the [method reference]({{ site.baseurl }}/method-reference/session.html#getauthorizeurl).
+
+#### Step 2
+When the user has approved your app, Spotify will redirect the user together with a `code` to the specifed redirect URI.
+You'll need to use this code to request a access token from Spotify and tell the API wrapper about the access token to use, like this:
+
+    require 'vendor/autoload.php';
+
+    $session = new SpotifyWebAPI\Session('CLIENT_ID', 'CLIENT_SECRET', 'REDIRECT_URI');
+    $api = new SpotifyWebAPI\SpotifyWebAPI();
+
+    // Request a access token using the code from Spotify
+    $session->requestAccessToken($_GET['code']);
+    $accessToken = $session->getAccessToken();
+
+    // Set the access token on the API wrapper
+    $api->setAccessToken($accessToken);
+
+    // Start using the API!
+
+When requesting a access token, a **refresh token** will also be included. This can be used to extend the validity of access tokens.
+To refresh a access token, the `refreshAccessToken()` method can be used:
+
+
+    $session->refreshAccessToken($refreshToken);
+
+
+You can also retrieve the refresh token and store it for later use:
+
+    $refreshToken = $session->getRefreshToken();
+
+    // Store it somewhere...
+
+Later, when you want to refresh a session with it, fetch it and request a new access token:
+
+    // Fetch an old refresh token from somewhere...
+
+    $session->refreshAccessToken($refreshToken);
+
+    $accessToken = $session->getAccessToken();
+
+    // Set the new access token on the API wrapper
+    $api->setAccessToken($accessToken);
+
+    // Continue as usual...
+
+### Client Credentials Flow
+This method doesn't require any user interaction and no access to user information are therefore granted.
+
+    require 'vendor/autoload.php';
+
+    $session = new SpotifyWebAPI\Session('CLIENT_ID', 'CLIENT_SECRET', 'REDIRECT_URI');
+    $api = new SpotifyWebAPI\SpotifyWebAPI();
+
+    // Request a access token with optional scopes
+    $scopes = array(
+        'playlist-read-private',
+        'user-read-private'
+    );
+
+    $session->requestCredentialsToken($scopes);
+    $accessToken = $session->getAccessToken(); // We're good to go!
+
+    // Set the code on the API wrapper
+    $api->setAccessToken($accessToken);
+
+    // Start using the API!
+
+As you can see, this flow is very similar to the Authorization Code Flow, however no refresh token is available.
+
+One big advantage with this flow is that it requires no user interaction and still increases the rate limit on your API calls.