Add more/better examples. Minor styling update

closes #336
closes #295
closes #327

css/main.scss

@@ -73,3 +73,12 @@ a {
 a:visited {
   color: darken($salmon, 10%);
 }
+
+ul {
+  li {
+    margin-bottom: 0;
+    p {
+      margin: 0;
+    }
+  }
+}

examples/authorization.md

@@ -2,7 +2,7 @@
 layout: default
 ---
 
-## Authorization and Making Requests
+## Authorization and making requests
 
 The library currently supports most authentication schemes that GitHub
 provides.

examples/gists.md

@@ -2,32 +2,37 @@
 layout: default
 ---
 
-## Reading and Manipulating Gists
+## Reading and manipulating gists
 
 ```javascript
 var GitHub = require('github-api');
 
 // unauthenticated client
-var gh = new GitHub();
+var gh = new GitHub({
+  username: 'foo',
+  password: 'bar'
+});
+
 var gist = gh.getGist(); // not a gist yet
-gist.create({
+var data = {
    public: true,
    description: 'My first gist',
    files: {
       "file1.txt": {
          contents: "Aren't gists great!"
       }
    }
-})
-// Promises!
-.then(function(httpResponse) {
-   var gistJson = httpResponse.data;
+};
 
-   // Callbacks too
-   gist.read(function(err, gist, xhr) {
-      // if no error occurred then err == null
-      // gistJson == httpResponse.data
-      // xhr == httpResponse
-   });
-});
+gist.create(data)
+  .then(function(httpResponse) {
+     var gistJson = httpResponse.data;
+
+     // Callbacks too
+     gist.read(function(err, gist, xhr) {
+        // if no error occurred then err == null
+        // gistJson == httpResponse.data
+        // xhr == httpResponse
+     });
+  });
 ```

examples/organizations.md

@@ -2,7 +2,7 @@
 layout: default
 ---
 
-## Organizations
+## Get an organization's repositories
 
 ```javascript
 var GitHub = require('github-api');

examples/ratelimit.md

@@ -0,0 +1,23 @@
+---
+layout: default
+---
+
+## Checking the ratelimit
+
+```javascript
+var GitHub = require('github-api');
+
+var gh = new GitHub();
+
+// check our rate-limit status
+// since we're unauthenticated the limit is 60 requests per hour
+gh.getRateLimit().getRateLimit()
+  .then(function(resp) {
+      console.log('Limit remaining: ' + resp.data.rate.remaining);
+      // date constructor takes epoch milliseconds and we get epoch seconds
+      console.log('Reset date: ' + new Date(resp.data.rate.reset * 1000));
+  }).catch(function(error) {
+      console.log('Error fetching rate limit', error.message);
+  });
+
+```

examples/users.md

@@ -4,23 +4,28 @@ layout: default
 
 # Users
 
+Note that when you `getUser()` you will get a user that represents the authenticated user. This will
+slightly change the calls to GitHub. In general you should have to worry about the differences between
+Listing [your repos](https://developer.github.com/v3/repos/#list-your-repositories) and listing
+[a user's repos](https://developer.github.com/v3/repos/#list-user-repositories) because things should just work.
+
 ```javascript
-var GitHub = require('github-api');
+import GitHub from 'github-api';
 
 // basic auth
-var gh = new GitHub({
+const gh = new GitHub({
    username: 'FOO',
    password: 'NotFoo'
 });
 
-var me = gh.getUser();
-me.getNotification(function(err, notifcations) {
+const me = gh.getUser();
+me.listNotification(function(err, notifcations) {
    // do some stuff
 });
 
-var clayreimann = gh.getUser('clayreimann');
-clayreimann.getStarredRepos()
-   .then(function(httpPromise) {
-      var repos = httpPromise.data;
+const clayreimann = gh.getUser('clayreimann');
+clayreimann.listStarredRepos()
+   .then(function({data: reposJson}) {
+     console.log(`clayreimann has ${reposJson.length} repos!`);
    });
 ```

examples/webhooks.md

@@ -0,0 +1,71 @@
+---
+layout: default
+---
+
+## List the webhooks for a user's repositories
+```javascript
+var GitHub = require("github-api");
+var Promise = require("es6-promise").Promise;
+
+var gh = new GitHub({
+  username: 'foo',
+  password: 'bar'
+});
+
+var user = 'slunk32';
+gh.getUser(user).getRepos()
+  // turn the json objects we fetched into `Repository`s
+  .then(function(httpPromise) {
+      return httpPromise.data.map(function(repoJson) {
+          // console.log('repo '  repoJson.name);
+          return gh.getRepo(user, repoJson.name);
+      });
+  })
+  // Curry promises to fetch webhooks
+   .then(function(repos) {
+      console.log(repos);
+      return Promise.all(repos.map(function(repo) {
+          return repo.listHooks();
+      }));
+   })
+   // Fetch the webhooks json
+   .then(function(listOfListOfHooks) {
+       listOfListOfHooks = listOfListOfHooks || []; // monkey-patch for non-authenticated users
+       listOfListOfHooks.forEach(function(hooksHttpResonse) {
+           console.log('hooks for '  hooksHttpResonse.config.url);
+           console.log(hooksHttpResonse.data);
+       });
+   })
+   .catch(function(error) {
+       console.log('an error occurred fetching the webhooks', error);
+   });
+```
+
+## Create a new webhook
+```javascript
+var GitHub = require("github-api");
+var Promise = require("es6-promise").Promise;
+
+var gh = new GitHub({
+  username: 'foo',
+  password: 'bar'
+});
+
+var fork = gh.getRepository('user', 'repo');
+
+var hookDef = {
+  "name" : "travis",
+  "config" : {
+    "user" : "your-Username",
+    "token" : "00000000000000000000000000",
+    "domain" : "http://notify.travis-ci.org",
+    "content_type": "json"
+  },
+  "events" : ["push", "pull_request"],
+  "active" : true
+ }
+fork.createHook(hookDef)
+  .then(function({data: hook}) {
+    console.log("A travis hook has been created which will trigger a build on push and pull request events...");
+  });
+```

index.md

@@ -13,23 +13,26 @@ Data can be retrieved from the API either using callbacks (as in versions < 1.0)
 or using a new promise-based API. For now the promise-based API just returns the
 raw HTTP request promise; this might change in the next version.
 
-{%for entry in site.data.versions %}
+{%for entry in site.data.versions reversed %}
 * [{{entry.version}}]({{site.baseurl}}/docs/{{entry.version}}/index.html)
 {%endfor%}
 
 #### Examples
 
-* [Authorization][authorization]
-* [Gists][gists]
-* [Users][users]
-* [Organizations][organizations]
-* Repositories
+* [Authorization][authorization-examples]
+* [Gists][gist-examples]
+* [Users][user-examples]
+* [Organizations][organization-examples]
+* [Webhooks][webhook-examples]
+* [Rate Limit][ratelimit-examples]
 
 #### Credits
 * Base styles: [Milligram](milligram)
 
 [milligram]: https://milligram.github.io/
-[gists]: {{site.baseurl}}/examples/gists
-[users]: {{site.baseurl}}/examples/users
-[organizations]: {{site.baseurl}}/examples/organizations
-[authorization]: {{site.baseurl}}/examples/authorization
+[gist-examples]: {{site.baseurl}}/examples/gists
+[user-examples]: {{site.baseurl}}/examples/users
+[organization-examples]: {{site.baseurl}}/examples/organizations
+[authorization-examples]: {{site.baseurl}}/examples/authorization
+[webhook-examples]: {{site.baseurl}}/examples/webhooks
+[ratelimit-examples]: {{site.baseurl}}/examples/ratelimit