From 1e95060e47d0ed21fdb76167f4a44d43eaa7f6eb Mon Sep 17 00:00:00 2001 From: Alexandre Terrasa Date: Tue, 9 Jun 2015 16:34:17 -0400 Subject: [PATCH] github: enhance Github documentation as example for Nitdoc README files Signed-off-by: Alexandre Terrasa --- lib/github/README.md | 71 ++++++++++++++++++++++++++++++++++++++++++++ lib/github/api.nit | 35 ++++++++++++---------- lib/github/github.nit | 5 +++- lib/github/github_curl.nit | 4 ++- 4 files changed, 97 insertions(+), 18 deletions(-) create mode 100644 lib/github/README.md diff --git a/lib/github/README.md b/lib/github/README.md new file mode 100644 index 0000000..64a7e98 --- /dev/null +++ b/lib/github/README.md @@ -0,0 +1,71 @@ +# Nit wrapper for Github API + +This module provides a Nit object oriented interface to access the Github api. + +## Accessing the API + +[[doc: GithubAPI]] + +### Authentification + +[[doc: GithubAPI::auth]] + +Token can also be recovered from user config with `get_github_oauth`. + +[[doc: get_github_oauth]] + +### Retrieving user data + +[[doc: load_user]] +[[doc: User]] +[[list: User]] + +### Retrieving repo data + +[[doc: load_repo]] +[[doc: Repo]] +[[list: Repo]] + +### Other data + +[[list: api]] + +### Advanced uses + +#### Caching + +[[doc: cache]] + +#### Custom requests + +[[doc: GithubAPI::get]] + +#### Change the user agent + +[[doc: GithubAPI::user_agent]] + +#### Debugging + +[[doc: verbose_lvl]] + +#### Using with GitLab + +If URL scheme of GitLab API follows the one of Github API, it may be possible to +configure this wrapper to use a custom URL. + +[[doc: api_url]] + +## Creating hooks + +Using this API you can create Github hooks able to respond to actions performed +on a repository. + +[[doc: hooks]] + +## Dealing with events + +GithubAPI can trigger different events depending on the hook configuration. + +[[doc: GithubEvent]] + +[[list: github::events]] diff --git a/lib/github/api.nit b/lib/github/api.nit index 6f7c7d9..0d5a67a 100644 --- a/lib/github/api.nit +++ b/lib/github/api.nit @@ -12,7 +12,7 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Nit object oriented interface to Github api. +# Nit object oriented interface to [Github api](https://developer.github.com/v3/). # # This modules reifies Github API elements as Nit classes. # @@ -21,11 +21,9 @@ module api import github_curl -# Interface to Github REST API. +# Client to Github API # -# Used by all `GithubEntity` to perform requests. -# -# Usage: +# To access the API you need an instance of a `GithubAPI` client. # # ~~~ # # Get Github authentification token. @@ -36,7 +34,7 @@ import github_curl # var api = new GithubAPI(token) # ~~~ # -# The API client allows to get Github API entities: +# The API client allows you to get Github API entities. # # ~~~ # var repo = api.load_repo("privat/nit") @@ -49,9 +47,16 @@ import github_curl # ~~~ class GithubAPI - # Github API OAuth token. + # Github API OAuth token + # + # To access your private ressources, you must + # [authenticate](https://developer.github.com/guides/basics-of-authentication/). + # + # For client applications, Github recommands to use the + # [OAuth tokens](https://developer.github.com/v3/oauth/) authentification method. + # + # # - # This token is used to authenticate the application on Github API. # Be aware that there is [rate limits](https://developer.github.com/v3/rate_limit/) # associated to the key. var auth: String @@ -140,9 +145,9 @@ class GithubAPI return res.as(JsonObject) end - # Get the Github user with `login`. + # Get the Github user with `login` # - # Returns `null` if the user cannot be found. + # Loads the `User` from the API or returns `null` if the user cannot be found. # # var api = new GithubAPI(get_github_oauth) # var user = api.load_user("Morriar") @@ -154,7 +159,7 @@ class GithubAPI # Get the Github repo with `full_name`. # - # Returns `null` if the repo cannot be found. + # Loads the `Repo` from the API or returns `null` if the repo cannot be found. # # var api = new GithubAPI(get_github_oauth) # var repo = api.load_repo("privat/nit") @@ -349,11 +354,10 @@ abstract class GithubEntity fun html_url: String do return json["html_url"].to_s end -# A Github user. +# A Github user # +# Provides access to [Github user data](https://developer.github.com/v3/users/). # Should be accessed from `GithubAPI::load_user`. -# -# See . class User super GithubEntity @@ -374,9 +378,8 @@ end # A Github repository. # +# Provides access to [Github repo data](https://developer.github.com/v3/repos/). # Should be accessed from `GithubAPI::load_repo`. -# -# See . class Repo super GithubEntity diff --git a/lib/github/github.nit b/lib/github/github.nit index 9bc63a8..d4d5904 100644 --- a/lib/github/github.nit +++ b/lib/github/github.nit @@ -12,7 +12,10 @@ # See the License for the specific language governing permissions and # limitations under the License. -# Github API related features. +# Nit wrapper for Github API +# +# This module provides a Nit object oriented interface to access the +# [Github api](https://developer.github.com/v3/). module github import cache diff --git a/lib/github/github_curl.nit b/lib/github/github_curl.nit index 62776e6..dea87e4 100644 --- a/lib/github/github_curl.nit +++ b/lib/github/github_curl.nit @@ -131,8 +131,10 @@ class GithubError redef fun to_s do return "[{name}] {super}" end +# Gets the Github token from `git` configuration +# # Return the value of `git config --get github.oauthtoken` -# return "" if no such a key +# or `""` if no key exists. fun get_github_oauth: String do var p = new ProcessReader("git", "config", "--get", "github.oauthtoken") -- 1.7.9.5