Misc doc changes (#143)

CHANGELOG.md

@@ -1,4 +1,4 @@
-# CHANGELOG
+# Changelog
 
 ## v1.3.0 (2022-06-29)
 

LICENSE → LICENSE.md

@@ -1,4 +1,4 @@
-The MIT License (MIT)
+# The MIT License (MIT)
 
 Copyright (c) 2016 Phil Burrows
 

README.md

@@ -1,16 +1,17 @@
-![CI](https://github.com/peburrows/goth/workflows/CI/badge.svg)
-
 # Goth
 
-<!-- MDOC !-->
+![CI](https://github.com/peburrows/goth/workflows/CI/badge.svg)
+
 
 Google + Auth = Goth
 
-A simple library to generate and retrieve OAuth2 tokens for use with Google Cloud Service accounts.
+A simple library to generate and retrieve OAuth2 tokens for use with Google
+Cloud Service accounts.
 
 ## Installation
 
-**Note:** below are instructions for using Goth v1.3+. For more information on earlier versions of Goth, [see v1.2.0 documentation on hexdocs.pm](https://hexdocs.pm/goth/1.2.0).
+**Note:** below are instructions for using Goth v1.3+. For more information on
+earlier versions of Goth, [see v1.2.0 documentation on hexdocs.pm](https://hexdocs.pm/goth/1.2.0).
 
 1. Add `:goth` to your list of dependencies in `mix.exs`.
 
@@ -29,7 +30,11 @@ A simple library to generate and retrieve OAuth2 tokens for use with Google Clou
      use Application
 
      def start(_type, _args) do
-       credentials = "GOOGLE_APPLICATION_CREDENTIALS_JSON" |> System.fetch_env!() |> Jason.decode!()
+       credentials =
+         "GOOGLE_APPLICATION_CREDENTIALS_JSON"
+         |> System.fetch_env!()
+         |> Jason.decode!()
+
        source = {:service_account, credentials}
 
        children = [
@@ -41,9 +46,10 @@ A simple library to generate and retrieve OAuth2 tokens for use with Google Clou
    end
    ```
 
-   If you set `GOOGLE_APPLICATION_CREDENTIALS` or `GOOGLE_APPLICATION_CREDENTIALS_JSON`, have a
-   `~/.config/gcloud/application_default_credentials.json` file, or deploy your application to
-   Google Cloud, you can omit the `:source` option:
+   If you set `GOOGLE_APPLICATION_CREDENTIALS` or
+   `GOOGLE_APPLICATION_CREDENTIALS_JSON`, have a
+   `~/.config/gcloud/application_default_credentials.json` file, or deploy your
+   application to Google Cloud, you can omit the `:source` option:
 
    ```elixir
    def start(_type, _args) do
@@ -89,7 +95,6 @@ A simple library to generate and retrieve OAuth2 tokens for use with Google Clou
 
 See `Goth.start_link/1` for more information about possible configuration options.
 
-<!-- MDOC !-->
 
 ## Upgrading from Goth 1.2
 
@@ -98,3 +103,10 @@ See [Upgrading from Goth 1.2](UPGRADE_GUIDE.md) guide for more information.
 ## Community resources
 
 - [How to upload on YouTube Data API with elixir ?](https://mrdotb.com/posts/upload-on-youtube-with-elixir/)
+
+## Copyright and License
+
+Copyright (c) 2016 Phil Burrows
+
+This work is free. You can redistribute it and/or modify it under the terms of
+the MIT License. See the [LICENSE.md](./LICENSE.md) file for more details.

UPGRADE_GUIDE.md

@@ -1,9 +1,8 @@
-## Upgrading from Goth 1.2
+# Upgrading from Goth 1.2
 
-Earlier versions of Goth relied on global application environment configuration which is deprecated
-in favour of a more direct and explicit approach in Goth v1.3+. Previously, Goth depended on on
-the HTTPoison HTTP client, but now it has an _optional_ dependency on Hackney. Thus, new projects
-using Goth and wanting to use Hackney will need to explicitly include it in the dependencies.
+Earlier versions of Goth relied on global application environment configuration
+which is deprecated in favour of a more direct and explicit approach in Goth
+v1.3+.
 
 Below is a step-by-step upgrade path from Goth 1.x to 1.3:
 

lib/goth.ex

@@ -1,6 +1,4 @@
 defmodule Goth do
-  @external_resource "README.md"
-
   @moduledoc """
   A Goth token server.
   """

lib/goth/token.ex

@@ -56,14 +56,14 @@ defmodule Goth.Token do
 
       See "Source" section below for more information.
 
-    * `:http_client` - a funtion that makes the HTTP request.
+    * `:http_client` - a function that makes the HTTP request.
 
       Can be one of the following:
 
         * `fun` - same as `{fun, []}`
 
-        * `{fun, opts}` - `fun` must be a 1-arity funtion that receives a keyword list with fields
-          `:method`, `:url`, `:headers`, and `:body` along with any passed `opts`. The funtion must return
+        * `{fun, opts}` - `fun` must be a 1-arity function that receives a keyword list with fields
+          `:method`, `:url`, `:headers`, and `:body` along with any passed `opts`. The function must return
           `{:ok, %{status: status, headers: headers, body: body}}` or `{:error, exception}`.
 
           See "Custom HTTP Client" section below for more information.
@@ -136,7 +136,7 @@ defmodule Goth.Token do
   ## Custom HTTP Client
 
   To use a custom HTTP client, define a function that receives a keyword list with fields
-  `:method`, `:url`, `:headers`, and `:body`. The funtion must return
+  `:method`, `:url`, `:headers`, and `:body`. The function must return
   `{:ok, %{status: status, headers: headers, body: body}}` or `{:error, exception}`.
 
   Here's an example with Finch:

mix.exs

@@ -14,11 +14,7 @@ defmodule Goth.Mixfile do
       source_url: @source_url,
       name: "Goth",
       description: description(),
-      docs: [
-        source_ref: "v#{@version}",
-        main: "readme",
-        extras: ["README.md", "CHANGELOG.md", "UPGRADE_GUIDE.md"]
-      ],
+      docs: docs(),
       deps: deps(),
       aliases: aliases(),
       preferred_cli_env: [
@@ -34,6 +30,10 @@ defmodule Goth.Mixfile do
     ]
   end
 
+  def aliases do
+    ["test.all": ["test --include integration"]]
+  end
+
   defp elixirc_paths(:test), do: ["lib", "test/support"]
   defp elixirc_paths(_), do: ["lib"]
 
@@ -49,8 +49,19 @@ defmodule Goth.Mixfile do
     ]
   end
 
-  def aliases do
-    ["test.all": ["test --include integration"]]
+  defp docs do
+    [
+      source_ref: "v#{@version}",
+      main: "readme",
+      extras: [
+        "CHANGELOG.md",
+        "README.md",
+        "UPGRADE_GUIDE.md",
+        "LICENSE.md"
+      ],
+      formatters: ["html"],
+      skip_undefined_reference_warnings_on: ["CHANGELOG.md"]
+    ]
   end
 
   defp description do
@@ -63,7 +74,10 @@ defmodule Goth.Mixfile do
     [
       maintainers: ["Phil Burrows"],
       licenses: ["MIT"],
-      links: %{"GitHub" => @source_url}
+      links: %{
+        "Changelog" => "#{@source_url}/blob/master/CHANGELOG.md",
+        "GitHub" => @source_url
+      }
     ]
   end
 end