Misc doc changes

Besides other documentation changes, this commit ensures the generated
HTML doc for HexDocs.pm will become the source of truth for this Elixir
library and leverage on latest features of ExDoc.

.formatter.exs

@@ -0,0 +1,4 @@
+# Used by "mix format"
+[
+  inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}"]
+]

.gitignore

@@ -5,6 +5,7 @@
 /_build
 /cover
 /deps
+/tmp
 erl_crash.dump
 *.ez
 *.beam
@@ -56,4 +57,4 @@ tags
 
 
 ### VS Code ###
-.elixir_ls
+.elixir_ls

CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
 ## v0.8.1
 
 * Adds the ability to read GitHub client credentials at runtime, rather than only at compile time.

README.md

@@ -1,20 +1,29 @@
 # Überauth GitHub
 
+[![Build Status](https://travis-ci.org/ueberauth/ueberauth_github.svg?branch=master)](https://travis-ci.org/ueberauth/ueberauth_github)
+[![Module Version](https://img.shields.io/hexpm/v/ueberauth_github.svg)](https://hex.pm/packages/ueberauth_github)
+[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/ueberauth_github/)
+[![Total Download](https://img.shields.io/hexpm/dt/ueberauth_github.svg)](https://hex.pm/packages/ueberauth_github)
+[![License](https://img.shields.io/hexpm/l/ueberauth_github.svg)](https://github.com/ueberauth/ueberauth_github/blob/master/LICENSE.md)
+[![Last Updated](https://img.shields.io/github/last-commit/ueberauth/ueberauth_github.svg)](https://github.com/ueberauth/ueberauth_github/commits/master)
+
 > GitHub OAuth2 strategy for Überauth.
 
 ## Installation
 
-1. Setup your application at [GitHub Developer](https://developer.github.com).
+1.  Setup your application at [GitHub Developer](https://developer.github.com).
 
-1. Add `:ueberauth_github` to your list of dependencies in `mix.exs`:
+2.  Add `:ueberauth_github` to your list of dependencies in `mix.exs`:
 
     ```elixir
     def deps do
-      [{:ueberauth_github, "~> 0.7"}]
+      [
+        {:ueberauth_github, "~> 0.7"}
+      ]
     end
     ```
 
-1. Add GitHub to your Überauth configuration:
+3.  Add GitHub to your Überauth configuration:
 
     ```elixir
     config :ueberauth, Ueberauth,
@@ -23,7 +32,7 @@
       ]
     ```
 
-1.  Update your provider configuration:
+4.  Update your provider configuration:
 
     ```elixir
     config :ueberauth, Ueberauth.Strategy.Github.OAuth,
@@ -39,21 +48,20 @@
       client_secret: {:system, "GITHUB_CLIENT_SECRET"}
     ```
 
-1.  Include the Überauth plug in your router:
+5.  Include the Überauth plug in your router:
 
     ```elixir
     defmodule MyApp.Router do
       use MyApp.Web, :router
 
-
       pipeline :browser do
         plug Ueberauth
         ...
        end
     end
     ```
 
-1.  Create the request and callback routes if you haven't already:
+6.  Create the request and callback routes if you haven't already:
 
     ```elixir
     scope "/auth", MyApp do
@@ -64,7 +72,8 @@
     end
     ```
 
-1. Your controller needs to implement callbacks to deal with `Ueberauth.Auth` and `Ueberauth.Failure` responses.
+7.  Your controller needs to implement callbacks to deal with `Ueberauth.Auth`
+    and `Ueberauth.Failure` responses.
 
 For an example implementation see the [Überauth Example](https://github.com/ueberauth/ueberauth_example) application.
 
@@ -78,7 +87,13 @@ Or with options:
 
     /auth/github?scope=user,public_repo
 
-By default the requested scope is "user,public\_repo". This provides both read and write access to the GitHub user profile details and public repos. For a read-only scope, either use "user:email" or an empty scope "". See more at [GitHub's OAuth Documentation](https://developer.github.com/apps/building-integrations/setting-up-and-registering-oauth-apps/about-scopes-for-oauth-apps/). Scope can be configured either explicitly as a `scope` query value on the request path or in your configuration:
+By default the requested scope is "user,public\_repo". This provides both read
+and write access to the GitHub user profile details and public repos. For a
+read-only scope, either use "user:email" or an empty scope "". See more at
+[GitHub's OAuth Documentation](https://developer.github.com/apps/building-integrations/setting-up-and-registering-oauth-apps/about-scopes-for-oauth-apps/).
+
+Scope can be configured either explicitly as a `scope` query value on the
+request path or in your configuration:
 
 ```elixir
 config :ueberauth, Ueberauth,
@@ -87,12 +102,15 @@ config :ueberauth, Ueberauth,
   ]
 ```
 
-It is also possible to disable the sending of the `redirect_uri` to GitHub. This is particularly useful
-when your production application sits behind a proxy that handles SSL connections. In this case,
-the `redirect_uri` sent by `Ueberauth` will start with `http` instead of `https`, and if you configured
-your GitHub OAuth application's callback URL to use HTTPS, GitHub will throw an `uri_missmatch` error.
+It is also possible to disable the sending of the `redirect_uri` to GitHub.
+This is particularly useful when your production application sits behind a
+proxy that handles SSL connections. In this case, the `redirect_uri` sent by
+`Ueberauth` will start with `http` instead of `https`, and if you configured
+your GitHub OAuth application's callback URL to use HTTPS, GitHub will throw an
+`uri_missmatch` error.
 
-To prevent `Ueberauth` from sending the `redirect_uri`, you should add the following to your configuration:
+To prevent `Ueberauth` from sending the `redirect_uri`, you should add the
+following to your configuration:
 
 ```elixir
 config :ueberauth, Ueberauth,
@@ -102,7 +120,11 @@ config :ueberauth, Ueberauth,
 ```
 
 ## Private Emails
-Github now allows you to keep your email address private. If you don't mind that you won't know a users email address you can specify `allow_private_emails`. This will set the users email as `[email protected]`.
+
+GitHub now allows you to keep your email address private. If you don't mind
+that you won't know a users email address you can specify
+`allow_private_emails`. This will set the users email as
+`[email protected]`.
 
 ```elixir
 config :ueberauth, Ueberauth,
@@ -111,6 +133,8 @@ config :ueberauth, Ueberauth,
   ]
 ```
 
-## License
+## Copyright and License
+
+Copyright (c) 2015 Daniel Neighman
 
-Please see [LICENSE](https://github.com/ueberauth/ueberauth_github/blob/master/LICENSE) for licensing details.
+This library is released under the MIT License. See the [LICENSE.md](./LICENSE.md) file

lib/ueberauth/strategy/github.ex

@@ -1,21 +1,22 @@
 defmodule Ueberauth.Strategy.Github do
   @moduledoc """
-  Provides an Ueberauth strategy for authenticating with Github.
+  Provides an Ueberauth strategy for authenticating with GitHub.
 
   ### Setup
 
   Create an application in Github for you to use.
 
-  Register a new application at: [your github developer page](https://github.com/settings/developers) and get the `client_id` and `client_secret`.
+  Register a new application at: [your github developer page](https://github.com/settings/developers)
+  and get the `client_id` and `client_secret`.
 
-  Include the provider in your configuration for Ueberauth
+  Include the provider in your configuration for Ueberauth;
 
       config :ueberauth, Ueberauth,
         providers: [
           github: { Ueberauth.Strategy.Github, [] }
         ]
 
-  Then include the configuration for github.
+  Then include the configuration for GitHub:
 
       config :ueberauth, Ueberauth.Strategy.Github.OAuth,
         client_id: System.get_env("GITHUB_CLIENT_ID"),
@@ -33,8 +34,8 @@ defmodule Ueberauth.Strategy.Github do
         get "/:provider/callback", AuthController, :callback
       end
 
-
-  Create an endpoint for the callback where you will handle the `Ueberauth.Auth` struct
+  Create an endpoint for the callback where you will handle the
+  `Ueberauth.Auth` struct:
 
       defmodule MyApp.AuthController do
         use MyApp.Web, :controller
@@ -48,16 +49,17 @@ defmodule Ueberauth.Strategy.Github do
         end
       end
 
-  You can edit the behaviour of the Strategy by including some options when you register your provider.
+  You can edit the behaviour of the Strategy by including some options when you
+  register your provider.
 
-  To set the `uid_field`
+  To set the `uid_field`:
 
       config :ueberauth, Ueberauth,
         providers: [
           github: { Ueberauth.Strategy.Github, [uid_field: :email] }
         ]
 
-  Default is `:id`
+  Default is `:id`.
 
   To set the default 'scopes' (permissions):
 
@@ -66,7 +68,8 @@ defmodule Ueberauth.Strategy.Github do
           github: { Ueberauth.Strategy.Github, [default_scope: "user,public_repo"] }
         ]
 
-  Default is empty ("") which "Grants read-only access to public information (includes public user profile info, public repository info, and gists)"
+  Default is empty ("") which "Grants read-only access to public information
+  (includes public user profile info, public repository info, and gists)"
   """
   use Ueberauth.Strategy,
     uid_field: :id,
@@ -80,11 +83,12 @@ defmodule Ueberauth.Strategy.Github do
   @doc """
   Handles the initial redirect to the github authentication page.
 
-  To customize the scope (permissions) that are requested by github include them as part of your url:
+  To customize the scope (permissions) that are requested by github include
+  them as part of your url:
 
       "/auth/github?scope=user,public_repo,gist"
 
-  You can also include a `state` param that github will return to you.
+  You can also include a `:state` param that github will return to you.
   """
   def handle_request!(conn) do
     scopes = conn.params["scope"] || option(conn, :default_scope)
@@ -105,8 +109,11 @@ defmodule Ueberauth.Strategy.Github do
   end
 
   @doc """
-  Handles the callback from Github. When there is a failure from Github the failure is included in the
-  `ueberauth_failure` struct. Otherwise the information returned from Github is returned in the `Ueberauth.Auth` struct.
+  Handles the callback from GitHub.
+
+  When there is a failure from Github the failure is included in the
+  `ueberauth_failure` struct. Otherwise the information returned from Github is
+  returned in the `Ueberauth.Auth` struct.
   """
   def handle_callback!(%Plug.Conn{params: %{"code" => code}} = conn) do
     module = option(conn, :oauth2_module)
@@ -127,7 +134,8 @@ defmodule Ueberauth.Strategy.Github do
   end
 
   @doc """
-  Cleans up the private area of the connection used for passing the raw Github response around during the callback.
+  Cleans up the private area of the connection used for passing the raw GitHub
+  response around during the callback.
   """
   def handle_cleanup!(conn) do
     conn
@@ -136,14 +144,16 @@ defmodule Ueberauth.Strategy.Github do
   end
 
   @doc """
-  Fetches the uid field from the Github response. This defaults to the option `uid_field` which in-turn defaults to `id`
+  Fetches the `:uid` field from the GitHub response.
+
+  This defaults to the option `:uid_field` which in-turn defaults to `:id`
   """
   def uid(conn) do
     conn |> option(:uid_field) |> to_string() |> fetch_uid(conn)
   end
 
   @doc """
-  Includes the credentials from the Github response.
+  Includes the credentials from the GitHub response.
   """
   def credentials(conn) do
     token = conn.private.github_token
@@ -161,7 +171,8 @@ defmodule Ueberauth.Strategy.Github do
   end
 
   @doc """
-  Fetches the fields to populate the info section of the `Ueberauth.Auth` struct.
+  Fetches the fields to populate the info section of the `Ueberauth.Auth`
+  struct.
   """
   def info(conn) do
     user = conn.private.github_user
@@ -193,7 +204,8 @@ defmodule Ueberauth.Strategy.Github do
   end
 
   @doc """
-  Stores the raw information (including the token) obtained from the Github callback.
+  Stores the raw information (including the token) obtained from the GitHub
+  callback.
   """
   def extra(conn) do
     %Extra{

lib/ueberauth/strategy/github/oauth.ex

@@ -1,12 +1,14 @@
 defmodule Ueberauth.Strategy.Github.OAuth do
   @moduledoc """
-  An implementation of OAuth2 for github.
+  An implementation of OAuth2 for GitHub.
 
-  To add your `client_id` and `client_secret` include these values in your configuration.
+  To add your `:client_id` and `:client_secret` include these values in your
+  configuration:
 
       config :ueberauth, Ueberauth.Strategy.Github.OAuth,
         client_id: System.get_env("GITHUB_CLIENT_ID"),
         client_secret: System.get_env("GITHUB_CLIENT_SECRET")
+
   """
   use OAuth2.Strategy
 
@@ -18,14 +20,18 @@ defmodule Ueberauth.Strategy.Github.OAuth do
   ]
 
   @doc """
-  Construct a client for requests to Github.
+  Construct a client for requests to GitHub.
 
-  Optionally include any OAuth2 options here to be merged with the defaults.
+  Optionally include any OAuth2 options here to be merged with the defaults:
 
-      Ueberauth.Strategy.Github.OAuth.client(redirect_uri: "http://localhost:4000/auth/github/callback")
+      Ueberauth.Strategy.Github.OAuth.client(
+        redirect_uri: "http://localhost:4000/auth/github/callback"
+      )
 
   This will be setup automatically for you in `Ueberauth.Strategy.Github`.
-  These options are only useful for usage outside the normal callback phase of Ueberauth.
+
+  These options are only useful for usage outside the normal callback phase of
+  Ueberauth.
   """
   def client(opts \\ []) do
     config =
@@ -46,7 +52,9 @@ defmodule Ueberauth.Strategy.Github.OAuth do
   end
 
   @doc """
-  Provides the authorize url for the request phase of Ueberauth. No need to call this usually.
+  Provides the authorize url for the request phase of Ueberauth.
+
+  No need to call this usually.
   """
   def authorize_url!(params \\ [], opts \\ []) do
     opts