mirror of
https://github.com/zoriya/octokit.net.git
synced 2026-06-05 03:30:34 +00:00
Merge pull request #948 from octokit/documentation
[WIP] Documentation Is A Nice Thing To Have™
This commit is contained in:
Brendan Forster
+4
-1
@@ -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/
|
||||
@@ -17,7 +17,7 @@ namespace Octokit.Tests.Clients
|
||||
|
||||
client.Get("fake", "repo");
|
||||
|
||||
connection.Received().Get<Page>(Arg.Is<Uri>(u => u.ToString() == "repos/fake/repo/pages"), null);
|
||||
connection.Received().Get<Page>(Arg.Is<Uri>(u => u.ToString() == "repos/fake/repo/pages"));
|
||||
}
|
||||
|
||||
[Fact]
|
||||
@@ -65,7 +65,7 @@ namespace Octokit.Tests.Clients
|
||||
|
||||
client.GetLatest("fake", "repo");
|
||||
|
||||
connection.Received().Get<PagesBuild>(Arg.Is<Uri>(u => u.ToString() == "repos/fake/repo/pages/builds/latest"), null);
|
||||
connection.Received().Get<PagesBuild>(Arg.Is<Uri>(u => u.ToString() == "repos/fake/repo/pages/builds/latest"));
|
||||
}
|
||||
|
||||
[Fact]
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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/`
|
||||
@@ -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<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:**
|
||||
|
||||
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.
|
||||
@@ -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,
|
||||
|
||||
+11
-17
@@ -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.
|
||||
|
||||
+165
-5
@@ -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
|
||||
}
|
||||
```
|
||||
|
||||
+39
@@ -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'
|
||||
Reference in New Issue
Block a user