Skip to content

Commit

Permalink
Update documentation due to the new http4s client requirement
Browse files Browse the repository at this point in the history
  • Loading branch information
BenFradet committed Mar 16, 2020
1 parent 5ef6dbd commit ab22c06
Show file tree
Hide file tree
Showing 13 changed files with 347 additions and 249 deletions.
32 changes: 18 additions & 14 deletions docs/docs/activity.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,23 +15,27 @@ with Github4s, you can interact with:
- [List stargazers](#list-stargazers)
- [List starred repositories](#list-starred-repositories)

The following examples use `cats.effect.IO` and assume the following imports and token:
The following examples assume the following code:

```scala mdoc:silent
import github4s.Github
import github4s.GithubIOSyntax._
import cats.effect.IO
import scala.concurrent.ExecutionContext.Implicits.global

implicit val IOContextShift = IO.contextShift(global)
val accessToken = sys.env.get("GITHUB4S_ACCESS_TOKEN")
```
import java.util.concurrent._

import cats.effect.{Blocker, ContextShift, IO}
import github4s.Github
import org.http4s.client.{Client, JavaNetClientBuilder}

They also make use of `cats.Id`, but any type container `F` implementing `ConcurrentEffect` will do.
import scala.concurrent.ExecutionContext.global

LiftIO syntax for `cats.Id` and `Future` are provided in `GithubIOSyntax`.
val httpClient: Client[IO] = {
val blockingPool = Executors.newFixedThreadPool(5)
val blocker = Blocker.liftExecutorService(blockingPool)
implicit val cs: ContextShift[IO] = IO.contextShift(global)
JavaNetClientBuilder[IO](blocker).create // use BlazeClientBuilder for production use
}

val accessToken = sys.env.get("GITHUB4S_ACCESS_TOKEN")
val gh = Github[IO](httpClient, accessToken)
```

## Notifications

Expand All @@ -48,7 +52,7 @@ You can subscribe or unsubscribe using `setThreadSub`; it takes as arguments:
- `ignored`: Determines if all notifications should be blocked from this thread.

```scala mdoc:compile-only
val threadSub = Github[IO](accessToken).activities.setThreadSub(5, true, false)
val threadSub = gh.activities.setThreadSub(5, true, false)
val response = threadSub.unsafeRunSync()
response.result match {
case Left(e) => println(s"Something went wrong: ${e.getMessage}")
Expand All @@ -73,7 +77,7 @@ You can list the users starring a specific repository with `listStargazers`; it
To list the stargazers of 47degrees/github4s:

```scala mdoc:compile-only
val listStargazers = Github[IO](accessToken).activities.listStargazers("47degrees", "github4s", true)
val listStargazers = gh.activities.listStargazers("47degrees", "github4s", true)
val response = listStargazers.unsafeRunSync()
response.result match {
case Left(e) => println(s"Something went wrong: ${e.getMessage}")
Expand Down Expand Up @@ -101,7 +105,7 @@ the repo was last pushed to), optional.
To list the starred repositories for user `rafaparadela`:

```scala mdoc:compile-only
val listStarredRepositories = Github[IO](accessToken).activities.listStarredRepositories("rafaparadela", true)
val listStarredRepositories = gh.activities.listStarredRepositories("rafaparadela", true)
val response = listStarredRepositories.unsafeRunSync()
response.result match {
case Left(e) => println(s"Something went wrong: ${e.getMessage}")
Expand Down
34 changes: 21 additions & 13 deletions docs/docs/auth.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,22 +13,29 @@ with Github4s, you can:
- [Authorize a url](#authorize-a-url)
- [Get an access token](#get-an-access-token)

The following examples assume the following imports:
The following examples assume the following code:

```scala mdoc:silent
import java.util.concurrent._

import cats.effect.{Blocker, ContextShift, IO}
import github4s.Github
import github4s.GithubIOSyntax._
import cats.effect.IO
import scala.concurrent.ExecutionContext.Implicits.global
import org.http4s.client.{Client, JavaNetClientBuilder}

implicit val IOContextShift = IO.contextShift(global)
```
They also make use of `cats.Id`, but any type container `F` implementing `ConcurrentEffect` will do.
import scala.concurrent.ExecutionContext.global

LiftIO syntax for `cats.Id` and `Future` are provided in `GithubIOSyntax`.
val httpClient: Client[IO] = {
val blockingPool = Executors.newFixedThreadPool(5)
val blocker = Blocker.liftExecutorService(blockingPool)
implicit val cs: ContextShift[IO] = IO.contextShift(global)
JavaNetClientBuilder[IO](blocker).create // use BlazeClientBuilder for production use
}

val gh = Github[IO](httpClient, None)
```

**NOTE**: In the examples you will see `Github(None)`
because if you are authenticating for the first time you don't have any access token yet.
**NOTE**: Above you can see `Github(httpClient, None)`. This is due to the fact that if you are
authenticating for the first time you don't have any access token yet.

### Create a new authorization token

Expand All @@ -43,7 +50,7 @@ You can create a new authorization token using `newAuth`; it takes as arguments:
- `client_secret`: the 40 character OAuth app client secret for which to create the token.

```scala mdoc:compile-only
val newAuth = Github[IO](None).auth.newAuth(
val newAuth = gh.auth.newAuth(
"rafaparadela",
"invalidPassword",
List("public_repo"),
Expand Down Expand Up @@ -73,7 +80,7 @@ You can authorize a url using `authorizeUrl`; it takes as arguments:
- `scopes`: attached to the token, for more information see [the scopes doc](https://developer.github.com/v3/oauth/#scopes).

```scala mdoc:compile-only
val authorizeUrl = Github[IO](None).auth.authorizeUrl(
val authorizeUrl = gh.auth.authorizeUrl(
"e8e39175648c9db8c280",
"http://localhost:9000/_oauth-callback",
List("public_repo"))
Expand Down Expand Up @@ -102,7 +109,7 @@ You can get an access token using `getAccessToken`; it takes as arguments:
- `state`: the unguessable random string you optionally provided in [Create a new authorization token](#create-a-new-authorization-token).

```scala mdoc:compile-only
val getAccessToken = Github[IO](None).auth.getAccessToken(
val getAccessToken = gh.auth.getAccessToken(
"e8e39175648c9db8c280",
"1234567890",
"code",
Expand All @@ -124,3 +131,4 @@ As you can see, a few features of the authorization endpoint are missing.
As a result, if you'd like to see a feature supported, feel free to create an issue and/or a pull request!

[auth-scala]: https://github.com/47degrees/github4s/blob/master/github4s/src/main/scala/github4s/domain/Authorization.scala
[http4s-client]: https://http4s.org/v0.21/client/
19 changes: 10 additions & 9 deletions docs/docs/contributing.md
Original file line number Diff line number Diff line change
Expand Up @@ -139,9 +139,10 @@ we'll be writing our tests in [GHReposSpec][repos-integ-spec]:

```scala
"Repos >> ListStatus" should "return a non empty list when a valid ref is provided" taggedAs Integration in {
val response = Github[IO](accessToken).repos
.listStatuses(validRepoOwner, validRepoName, validCommitSha, headers = headerUserAgent)
.unsafeRunSync()
val response = client.use { client =>
Github[IO](client, accessToken).repos
.listStatuses(validRepoOwner, validRepoName, validCommitSha, headers = headerUserAgent)
}.unsafeRunSync()

testIsRight[List[Status]](response, { r =>
r.nonEmpty shouldBe true
Expand All @@ -150,9 +151,11 @@ we'll be writing our tests in [GHReposSpec][repos-integ-spec]:
}

it should "return an error when an invalid ref is provided" taggedAs Integration in {
val response = Github[IO](accessToken).repos
.listStatuses(validRepoOwner, validRepoName, invalidRef, headers = headerUserAgent)
.unsafeRunSync()
val response = client.use { client =>
Github[IO](client, accessToken).repos
.listStatuses(validRepoOwner, validRepoName, invalidRef, headers = headerUserAgent)
}.unsafeRunSync()

testIsLeft(response)
response.statusCode shouldBe notFoundStatusCode
}
Expand Down Expand Up @@ -208,9 +211,7 @@ You can also list statuses through `listStatuses`; it take as arguments:
To list the statuses for a specific ref:
{triple backtick}scala mdoc:silent
val listStatuses =
Github[IO](accessToken).repos.listStatuses("47degrees", "github4s", "heads/master")
val listStatuses = gh.repos.listStatuses("47degrees", "github4s", "heads/master")
val response = listStatuses.unsafeRunSync()
response.result match {
case Left(e) => println(s"Something went wrong: ${e.getMessage}")
Expand Down
Loading

0 comments on commit ab22c06

Please sign in to comment.