diff --git a/.gitignore b/.gitignore index 54aa4b89..cd85843f 100644 --- a/.gitignore +++ b/.gitignore @@ -1,5 +1,5 @@ # Windows image file caches -Thumbs.db +Thumbs.db # Folder config file Desktop.ini @@ -86,5 +86,8 @@ tools/Octokit.CodeFormatter *.pdb pingme.txt +# ReadTheDocs build output +docs/_build + # it's 2015, no need to keep this around when migrating projects Backup/ \ No newline at end of file diff --git a/Octokit.Tests/Clients/RepositoryPagesClientTests.cs b/Octokit.Tests/Clients/RepositoryPagesClientTests.cs index e783b48a..dbafeb1a 100644 --- a/Octokit.Tests/Clients/RepositoryPagesClientTests.cs +++ b/Octokit.Tests/Clients/RepositoryPagesClientTests.cs @@ -17,7 +17,7 @@ namespace Octokit.Tests.Clients client.Get("fake", "repo"); - connection.Received().Get(Arg.Is(u => u.ToString() == "repos/fake/repo/pages"), null); + connection.Received().Get(Arg.Is(u => u.ToString() == "repos/fake/repo/pages")); } [Fact] @@ -65,7 +65,7 @@ namespace Octokit.Tests.Clients client.GetLatest("fake", "repo"); - connection.Received().Get(Arg.Is(u => u.ToString() == "repos/fake/repo/pages/builds/latest"), null); + connection.Received().Get(Arg.Is(u => u.ToString() == "repos/fake/repo/pages/builds/latest")); } [Fact] diff --git a/README.md b/README.md index 253c63e2..80f0cc2b 100644 --- a/README.md +++ b/README.md @@ -44,11 +44,11 @@ In Xamarin Studio you can find this option under the project's context menu: **A ## Documentation -Please see https://github.com/octokit/octokit.net/blob/master/docs/index.md for more detailed documentation. +Documentation is available at http://octokitnet.readthedocs.org/en/latest/. ## Build -Octokit is a single assembly designed to be easy to deploy anywhere. If you +Octokit is a single assembly designed to be easy to deploy anywhere. If you prefer to compile it yourself, you’ll need: * Visual Studio 2015 or Xamarin Studio @@ -65,14 +65,14 @@ cd Octokit ## Contribute -Visit the [Contributor Guidelines](https://github.com/octokit/octokit.net/blob/master/CONTRIBUTING.md) +Visit the [Contributor Guidelines](https://github.com/octokit/octokit.net/blob/master/CONTRIBUTING.md) for more details. ## Problems? -Octokit is 100% certified to be bug free. If you find an issue with our -certification, please visit the [issue tracker](https://github.com/octokit/octokit.net/issues) -and report the issue. +Octokit is 100% certified to be bug free. If you find an issue with our +certification, please visit the [issue tracker](https://github.com/octokit/octokit.net/issues) +and report the issue. Please be kind and search to see if the issue is already logged before creating a new one. If you're pressed for time, log it anyways. @@ -84,7 +84,7 @@ When creating an issue, clearly explain * What actually happened. * Steps to reproduce the problem. -Also include any other information you think is relevant to reproduce the +Also include any other information you think is relevant to reproduce the problem. ## Related Projects diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 00000000..07431750 --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,30 @@ +These instructions are for users who would like to get this documentation site running locally, +so you can edit changes and view them immediately. + +## Windows + +You need these things: + + - this repo - `git clone https://github.com/octokit/octokit.net.git` + - Python - install it from Chocolatey: `cinst python` + - mkdocs - install it with pip: `pip install mkdocs` + +**NOTE**: of course mkdocs doesn't appear on your PATH after this. Ugh. It's 2016. Come on people. + +**HACK**: add this to your PATH - `C:\ProgramData\chocolatey\lib\python3\tools\Scripts` and restart your shell. + +Once you've got all that, run `mkdocs serve` from the root of your repository and then point your browser +to `http://localhost:8000/` + +**NOTE**: You'll probably get a dialog here to give `python.exe` permission to open port 8000 on your firewall. This is fine. + +## OS X + +You need these things: + + - this repo - `git clone https://github.com/octokit/octokit.net.git` + - Python - if you don't have it already, get it from homebrew: `brew install python3` + - mkdocs - install it with pip: `pip install mkdocs` + +Once you've got all that, run `mkdocs serve` from the root of your repository and then point your browser +to `http://localhost:8000/` diff --git a/docs/demos/exploring-pull-requests.md b/docs/demos/exploring-pull-requests.md new file mode 100644 index 00000000..2ed5ab7c --- /dev/null +++ b/docs/demos/exploring-pull-requests.md @@ -0,0 +1,89 @@ +**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. + +``` +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>(); + + // 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 { 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:** + +I'm using the Octokit.Reactive package as this helps represent the flow than +tasks. This code also isn't very advanced - it could be more clever, but it +works for what I needed. diff --git a/docs/getting-started.md b/docs/getting-started.md index d76fa074..72695448 100644 --- a/docs/getting-started.md +++ b/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, diff --git a/docs/index.md b/docs/index.md index 379fe656..ae79d333 100644 --- a/docs/index.md +++ b/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. diff --git a/docs/search.md b/docs/search.md index c8cd57e5..a3536579 100644 --- a/docs/search.md +++ b/docs/search.md @@ -115,16 +115,176 @@ var request = new SearchIssuesRequest("linux") }; ``` - - ## Search Repositories -**TODO** +To search for repositories using Octokit you need to create a `SearchRepositoriesRequest` and populate it with the search criteria. + +```csharp +// Initialize a new instance of the SearchRepositoriesRequest class +var request = new SearchRepositoriesRequest(); + +// you can also specify a search term here +var request = new SearchRepositoriesRequest("bootstrap"); + +var result = await githubClient.Search.SearchRepo(request); +``` + +Now we can further filter our search. + +```csharp +var request = new SearchRepositoriesRequest("mvc client side framework") +{ + // lets find a library with over 1k stars + Stars = Range.GreaterThan(1000), + + // we can specify how big we want the repo to be in kilobytes + Size = Range.GreaterThan(1), + + // maybe we want the library to have over 50 forks? + Forks = Range.GreaterThan(50), + + // we may want to include or exclude the forks too + Fork = ForkQualifier.IncludeForks, + + // how about we restrict the language the library is written in? + Language = Language.JavaScript, + + // maybe we want to include searching in the read me? + In = new[] { InQualifier.Readme }, + + // or go all out and search the readme, name or description? + In = new[] { InQualifier.Readme, InQualifier.Description, InQualifier.Name }, + + // how about searching for libraries created after a given date? + Created = DateRange.GreaterThan(new DateTime(2015, 1, 1)), + + // or maybe check for repos that have been updated between a given date range? + Updated = DateRange.Between(new DateTime(2012, 4, 30), new DateTime(2012, 7, 4)), + + // we can also restrict the owner of the repo if we so wish + User = "dhh" +}; +``` + +We can also sort our results, the default sort direction is descending + +```csharp +var request = new SearchRepositoriesRequest("mvc client side framework") +{ + // sort by the number of stars + SortField = RepoSearchSort.Stars, + + // or by forks? + SortField = RepoSearchSort.Forks, + + // how about changing that sort direction? + Order = SortDirection.Ascending +} +``` ## Search Code -**TODO** +To search for code using Octokit you need to create a `SearchCodeRequest` and populate it with the search criteria. + +```csharp +// Initialize a new instance of the SearchCodeRequest class with a search term +var request = new SearchCodeRequest("auth"); + +// Or we can restrict the search to a specific repo +var request = new SearchCodeRequest("auth", "dhh", "rails"); + +var result = await githubClient.Search.SearchCode(request); +``` + +Now we can further filter our search. + +```csharp +var request = new SearchCodeRequest("auth") +{ + // we can restrict search to the file, path or search both + In = new[] { CodeInQualifier.File, CodeInQualifier.Path }, + + // how about we find a file based on a certain language + Language = Language.JavaScript, + + // do we want to search forks too? + Forks = true, + + // find files that are above 1000 bytes + Size = Range.GreaterThan(1000), + + // we may want to restrict the search to the path of a file + Path = "app/assets", + + // we may want to restrict the file based on file extension + Extension = "json", + + // restrict search to a specific file name + FileName = "app.json", + + // search within a users or orgs repo + User = "dhh" +}; +``` + +We can also sort our results by indexed or leave as null for best match. + +```csharp +var request = new SearchCodeRequest("dhh") +{ + // sort by last indexed + SortField = CodeSearchSort.Indexed +} +``` ## Search Users -**TODO** +To search for users using Octokit you need to create a `SearchUsersRequest` and populate it with the search criteria. + +```csharp +// Initialize a new instance of the SearchUsersRequest class with a search term +var request = new SearchUsersRequest("dhh"); + +var result = await githubClient.Search.SearchUsers(request); +``` + +Now we can further filter our search. + +```csharp +var request = new SearchUsersRequest("dhh") +{ + // lets find user with over 1k followers + Followers = Range.GreaterThan(1000), + + // find a user created after the date + Created = DateRange.GreaterThan(new DateTime(2015, 1, 1)), + + // we can search the location of a user, found a martian anyone? + Location = "Mars", + + // find a user that has over 100 repos + Repositories = Range.GreaterThan(100), + + // how about we find users that have a repo that match a certain language + Language = Language.JavaScript, + + // we may want to restrict to orgs or users only + AccountType = AccountSearchType.Org, + + // maybe we want to peek the username only? + In = new[] { UserInQualifier.Username }, + + // or go all out and search username, email and fullname? + In = new[] { UserInQualifier.Username, UserInQualifier.Email, UserInQualifier.Fullname }, +}; +``` + +We can also sort our results, by Followers, Repositories, Joined or leave as null for best match. + +```csharp +var request = new SearchUsersRequest("dhh") +{ + // sort by the number of followers + SortField = UsersSearchSort.Followers +} +``` diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 00000000..713d7cbf --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,39 @@ +site_name : Octokit.net Documentation +site_description: A GitHub API client for .NET + +dev_addr: '0.0.0.0:8000' + +repo_url: https://github.com/octokit/octokit.net/ + +docs_dir: docs/ +site_dir: docs/_build/ + +theme: readthedocs +#theme_dir: ./theme/mkdocs/ +#theme_center_lead: false + +pages: +- 'Home' : 'index.md' + +- 'Getting Started' : getting-started.md + +- Features: + - 'Issues' : 'issues.md' + - 'Labels' : 'labels.md' + - 'Milestones' : 'milestones.md' + - 'Releases' : 'releases.md' + - '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' + - 'HttpClient': 'http-client.md' + +- Contributing: + - 'Shipping Releases' : 'shipping-releases.md' + - 'Strong Naming' : 'strong-naming.md' + - 'Documentation': 'contributing.md'