added a sample script using Octokit

docs/demos/exploring-pull-requests.md

@@ -0,0 +1,90 @@
+**Scenario:** I have a lot of small pull requests to review, but things are a mess
+- old pull requests which might be superseded by new ones, and it's hard to see from
+the descriptions what the changes actually represent.
+
+**Goal:** a list of files, ordered by the number of pull requests which modify the
+file (most popular at the top). This then gives me a list of pull requests that I
+can review as a group.
+
+**Code**
+
+I'm using the Octokit.Reactive package as this helps represent the flow than tasks.
+
+```
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Reactive.Linq;
+using Octokit;
+using Octokit.Internal;
+using Octokit.Reactive;
+
+class Program
+{
+    static string owner = "github";
+    static string name = "gitignore";
+
+    static InMemoryCredentialStore credentials = new InMemoryCredentialStore(new Credentials("your-token-here"));
+    static ObservableGitHubClient client = new ObservableGitHubClient(new ProductHeaderValue("ophion"), credentials);
+
+    static void Main(string[] args)
+    {
+        var request = new PullRequestRequest();
+
+        var results = new Dictionary<string, List<int>>();
+
+        // fetch all open pull requests
+        client.PullRequest.GetAllForRepository(owner, name, request)
+            .SelectMany(pr =>
+            {
+                // for each pull request, get the files and associate
+                // with the pull request number - this is a bit kludgey
+                return client.PullRequest.Files(owner, name, pr.Number)
+                    .Select(file => Tuple.Create(pr.Number, file.FileName));
+            })
+            .Subscribe(data =>
+                {
+                    if (results.ContainsKey(data.Item2))
+                    {
+                        // if we're already tracking this file, add it
+                        results[data.Item2].Add(data.Item1);
+                    }
+                    else
+                    {
+                        // otherwise, we create a new list
+                        var list = new List<int> { data.Item1 };
+                        results[data.Item2] = list;
+                    }
+                },
+                ex =>
+                {
+                    Console.WriteLine("Exception found: " + ex.ToString());
+                },
+                () =>
+                {
+                    // after that's done, let's sort by the most popular files
+                    var sortbyPopularity = results
+                        .OrderByDescending(kvp => kvp.Value.Count);
+
+                    // output each file with the related pull requests
+                    foreach (var file in sortbyPopularity)
+                    {
+                        Console.WriteLine("File: {0}", file.Key);
+
+                        foreach (var id in file.Value)
+                        {
+                            Console.WriteLine(" - PR: {0}", id);
+                        }
+
+                        Console.WriteLine();
+                    }
+                });
+
+        // this will take a while, let's wait for user input before exiting
+        Console.ReadLine();
+    }
+}
+```
+
+
+**Notes:**

docs/getting-started.md

@@ -35,7 +35,7 @@ It is **strongly recommended** to use the [OAuth Flow](https://github.com/octoki
 
 When authenticated, you have 5000 requests per hour available. So this is the recommended approach for interacting with the API.
 
-### Connecting to GitHub Enterprise
+### Connect to GitHub Enterprise
 
 Octokit also supports connecting to GitHub Enterprise environments - just provide the URL to your GitHub Enterprise server when creating the client.
 
@@ -44,11 +44,11 @@ var ghe = new Uri("https://github.myenterprise.com/");
 var client = new GitHubClient(new ProductHeaderValue("my-cool-app"), ghe);
 ```
 
-### Get exploring
+### Get some data
 
-Once you've got that setup, the simplest thing to experiment with is fetching details about a specific user:
+Once you have that setup, the simplest thing to experiment with is fetching details about a specific user:
 
-```
+```csharp
 var user = await client.User.Get("shiftkey");
 Console.WriteLine("{0} has {1} public repositories - go check out their profile at {2}",
 	user.Name,

docs/index.md

@@ -1,24 +1,18 @@
 # Octokit.net
 
-This is a place for putting together some introductory documentation about how to use Octokit.net.
+If you are new to Octokit, I recommend reading the
+[Getting Started](https://github.com/octokit/octokit.net/blob/master/docs/getting-started.md)
+guide, which walks through configuring the basics.
 
- - [Getting Started](https://github.com/octokit/octokit.net/blob/master/docs/getting-started.md)
- - [OAuth Flow](https://github.com/octokit/octokit.net/blob/master/docs/oauth-flow.md)
- - [Releases API](https://github.com/octokit/octokit.net/blob/master/docs/releases.md)
- - [Git Database API](https://github.com/octokit/octokit.net/blob/master/docs/git-database.md)
+When you're done with that, have a look at the topics listed under **Features** to get
+an idea of what other things are available.
 
+If you're looking for some real-world examples, check out the **Samples** section.
 
-Possible topics to cover:
+There's also some advanced topics which require familiarity with the internals of Octokit.
+You shouldn't need to know these well, but they're there if there comes a day when you do.
 
- - Working with Repositories
- - Working with User data
- - Searching Repositories
- - ...
-
-If you're not sure where to start, there's a suite of 
+If we still haven't covered a topic you're interested in,  check out the suite of 
 [integration tests](https://github.com/octokit/octokit.net/tree/master/Octokit.Tests.Integration/Clients)
-which can help you to get familiar with how things currently work.
-
-Love and Octocats,
-
-The Octokit.net Team
+which can help you to get familiar with how things currently work. Then open an issue
+against the repository, so we can properly document things.

mkdocs.yml

@@ -25,6 +25,9 @@ pages:
   - 'Search' : 'search.md'
   - 'Git Database' : 'git-database.md'
 
+- Samples:
+  - 'Exploring Pull Requests' : 'demos/exploring-pull-requests.md'
+
 - Advanced:
   - 'Debugging from Source': 'debugging-source.md'
   - 'OAuth Flow': 'oauth-flow.md'