Misc doc changes (#706)

Besides other documentation changes, this commit includes all relevant documents to the generated HTML doc for HexDocs.pm and leverages on latest features of ExDoc.
beam-community · Jan 26, 2022 · 0c29aae · 0c29aae
1 parent e593641
commit 0c29aae
Show file tree

Hide file tree

Showing 5 changed files with 104 additions and 68 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,19 +1,39 @@
-/_build
-/deps
+# The directory Mix will write compiled artifacts to.
+/_build/
+
+# If you run "mix test --cover", coverage assets end up here.
+/cover/
+
+# The directory Mix downloads your dependencies sources to.
+/deps/
+
+# Where third-party dependencies like ExDoc output generated docs.
+/doc/
+
+# Ignore .fetch files in case you like to edit your project deps locally.
+/.fetch
+
+# If the VM crashes, it generates a dump, let's ignore it too.
 erl_crash.dump
+
+# Also ignore archive artifacts (built via "mix archive.build").
 *.ez
-config/config.secret.exs
-/doc
-.DS_Store
-tags
 
-# elixir LS files
+# Ignore package tarball (built via "mix hex.build").
+stripity_stripe-*.tar
 
-/.elixir_ls
-/.devcontainer
-# IntelliJ IDEA files
+# Temporary files, for example, from tests.
+/tmp/
 
-/.idea
+# Elixir LS files.
+.elixir_ls
+.devcontainer
+
+# IntelliJ IDEA files
+.idea
 *.iml
-priv/plts/*
-/cover
+
+# Misc.
+.DS_Store
+config/config.secret.exs
+tags
diff --git a/LICENSE → LICENSE.md b/LICENSE → LICENSE.md
@@ -1,20 +1,24 @@
-New BSD License
+# New BSD License
+
 http://www.opensource.org/licenses/bsd-license.php
+
 Copyright (c) 2015-2016, Rob Conery
-              2016, Code Corps PBC and Strumber
+
+Copyright (c) 2016, Code Corps PBC and Strumber
+
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without modification,
 are permitted provided that the following conditions are met:
 
-Redistributions of source code must retain the above copyright notice, this list
+1. Redistributions of source code must retain the above copyright notice, this list
 of conditions and the following disclaimer.
 
-Redistributions in binary form must reproduce the above copyright notice, this
+2. Redistributions in binary form must reproduce the above copyright notice, this
 list of conditions and the following disclaimer in the documentation and/or
 other materials provided with the distribution.
 
-Neither the names Code Corps nor Strumber, nor the names of its contributors may
+3. Neither the names Code Corps nor Strumber, nor the names of its contributors may
 be used to endorse or promote products derived from this software without
 specific prior written permission.
 

diff --git a/README.md b/README.md
@@ -41,21 +41,21 @@ Starting with stripity_stripe version 2.5.0, you can specify the Stripe API Vers
 
 Install the dependency by version:
 
-```ex
+```elixir
 {:stripity_stripe, "~> 2.0"}
 ```
 
 Or by commit reference (still awaiting hex publish rights so this is your best best for now):
 
-```ex
+```elixir
 {:stripity_stripe, git: "https://github.com/code-corps/stripity_stripe", ref: "8c091d4278d29a917bacef7bb2f0606317fcc025"}
 ```
 
 Next, add to your applications:
 
 _Not necessary if using elixir >= 1.4_
 
-```ex
+```elixir
 defp application do
   [applications: [:stripity_stripe]]
 end
@@ -65,7 +65,7 @@ end
 
 To make API calls, it is necessary to configure your Stripe secret key.
 
-```ex
+```elixir
 use Mix.Config
 
 config :stripity_stripe, api_key: System.get_env("STRIPE_SECRET")
@@ -75,31 +75,31 @@ config :stripity_stripe, api_key: "YOUR SECRET KEY"
 
 It's possible to use a function or a tuple to resolve the secret:
 
-```ex
+```elixir
 config :stripity_stripe, api_key: {MyApp.Secrets, :stripe_secret, []}
 # OR
 config :stripity_stripe, api_key: fn -> System.get_env("STRIPE_SECRET") end
 ```
 
 Moreover, if you are using Poison instead of Jason, you can configure the library to use Poison like so:
 
-```ex
+```elixir
 config :stripity_stripe, json_library: Poison
 ```
 
 ### Timeout
 
 To set timeouts, pass opts for the http client. The default one is Hackney.
 
-```ex
+```elixir
 config :stripity_stripe, hackney_opts: [{:connect_timeout, 1000}, {:recv_timeout, 5000}]
 ```
 
 ### Request Retries
 
 To set retries, you can pass the number of attempts and range of backoff (time between attempting the request again) in milliseconds.
 
-```ex
+```elixir
 config :stripity_stripe, :retries, [max_attempts: 3, base_backoff: 500, max_backoff: 2_000]
 ```
 
@@ -237,13 +237,13 @@ Works with API version 2015-10-16
 
 Install the dependency:
 
-```ex
+```elixir
 {:stripity_stripe, "~> 1.6"}
 ```
 
 Next, add to your applications:
 
-```ex
+```elixir
 defp application do
   [applications: [:stripity_stripe]]
 end
@@ -253,7 +253,7 @@ end
 
 To make API calls, it is necessary to configure your Stripe secret key (and optional platform client id if you are using Stripe Connect):
 
-```ex
+```elixir
 use Mix.Config
 
 config :stripity_stripe, secret_key: "YOUR SECRET KEY"
@@ -275,13 +275,13 @@ I've tried to make the API somewhat comprehensive and intuitive. If you'd like t
 
 In general, if Stripe requires some information for a given API call, you'll find that as part of the arity of the given function. For instance if you want to delete a Customer, you'll find that you _must_ pass the id along:
 
-```ex
+```elixir
 {:ok, result} = Stripe.Customers.delete "some_id"
 ```
 
 For optional arguments, you can send in a Keyword list that will get translated to parameters. So if you want to update a Subscription, for instance, you must send in the `customer_id` and `subscription_id` with the list of changes:
 
-```ex
+```elixir
 # Change customer to the Premium subscription
 {:ok, result} = Stripe.Customers.change_subscription "customer_id", "sub_id", [plan: "premium"]
 ```
@@ -290,7 +290,7 @@ Metadata (metadata:) key is supported on most object type and allow the storage
 
 That's the rule of thumb with this library. If there are any errors with your call, they will bubble up to you in the `{:error, message}` match.
 
-```ex
+```elixir
 # Example of paging through events
 {:ok, events} = Stripe.Events.list(key, "", 100) # second arg is a marker for paging
 
@@ -312,7 +312,7 @@ Stripe Connect allows you to provide your customers with an easy onboarding to t
 
 First, you need to register your platform on Stripe Connect to obtain a `client_id`. In your account settings, there's a "Connect" tab, select it. Then fill the information to activate your connect platform settings. The select he `client_id` (notice there's one for dev and one for prod), stash this `client_id` in the config file under
 
-```ex
+```elixir
 config :stripity_stripe, platform_client_id: "ac_???"
 ```
 
@@ -325,7 +325,7 @@ Here's an example of a button to start the workflow:
 
 You can generate this URL using:
 
-```ex
+```elixir
 url = Stripe.Connect.generate_button_url csrf_token
 ```
 
@@ -343,14 +343,14 @@ or
 
 Using the code request parameter, you make the following call:
 
-```ex
+```elixir
 {:ok, resp} -> Stripe.Connect.oauth_token_callback code
 resp[:access_token]
 ```
 
 `resp` will look like this:
 
-```ex
+```elixir
 %{
   token_type: "bearer",
   stripe_publishable_key: PUBLISHABLE_KEY,
@@ -383,7 +383,7 @@ Feedback, feature requests, and fixes are welcomed and encouraged. Please make a
 
 # License
 
-Please see [LICENSE](LICENSE) for licensing details.
+Please see [LICENSE.md](./LICENSE.md) for licensing details.
 
 # History
 

diff --git a/mix.exs b/mix.exs
@@ -1,16 +1,16 @@
 defmodule Stripe.Mixfile do
   use Mix.Project
 
+  @source_url "https://github.com/code-corps/stripity_stripe"
+  @version "2.12.1"
+
   def project do
     [
       app: :stripity_stripe,
-      deps: deps(),
-      description: description(),
-      dialyzer: [
-        plt_add_apps: [:mix],
-        plt_file: {:no_warn, "priv/plts/stripity_stripe.plt"}
-      ],
+      version: @version,
       elixir: "~> 1.10",
+      deps: deps(),
+      docs: docs(),
       package: package(),
       elixirc_paths: elixirc_paths(Mix.env()),
       preferred_cli_env: [
@@ -19,15 +19,11 @@ defmodule Stripe.Mixfile do
         "coveralls.post": :test,
         "coveralls.html": :test
       ],
-      test_coverage: [tool: ExCoveralls],
-      version: "2.12.1",
-      source_url: "https://github.com/code-corps/stripity_stripe/",
-      docs: [
-        main: "readme",
-        extras: ["README.md"],
-        groups_for_modules: groups_for_modules(),
-        nest_modules_by_prefix: nest_modules_by_prefix()
-      ]
+      dialyzer: [
+        plt_add_apps: [:mix],
+        plt_file: {:no_warn, "priv/plts/stripity_stripe.plt"}
+      ],
+      test_coverage: [tool: ExCoveralls]
     ]
   end
 
@@ -45,7 +41,7 @@ defmodule Stripe.Mixfile do
   defp elixirc_paths(:test), do: ["lib", "test/support"]
   defp elixirc_paths(_), do: ["lib"]
 
-  defp env() do
+  defp env do
     [
       api_base_url: "https://api.stripe.com/v1/",
       api_upload_url: "https://files.stripe.com/v1/",
@@ -59,12 +55,12 @@ defmodule Stripe.Mixfile do
 
   defp apps(:test), do: apps()
   defp apps(_), do: apps()
-  defp apps(), do: [:hackney, :logger, :jason, :uri_query]
+  defp apps, do: [:hackney, :logger, :jason, :uri_query]
 
   defp deps do
     [
       {:dialyxir, "1.1.0", only: [:dev, :test], runtime: false},
-      {:ex_doc, "~> 0.23.0", only: :dev},
+      {:ex_doc, ">= 0.0.0", only: :dev, runtime: false},
       {:excoveralls, "~> 0.14.1", only: :test},
       {:hackney, "~> 1.15"},
       {:inch_ex, "~> 2.0", only: [:dev, :test]},
@@ -76,20 +72,36 @@ defmodule Stripe.Mixfile do
     ]
   end
 
-  defp description do
-    """
-    A Stripe client for Elixir.
-    """
+  defp docs do
+    [
+      extras: [
+        "CHANGELOG.md": [title: "Changelog"],
+        "LICENSE.md": [title: "License"],
+        "README.md": [title: "Overview"]
+      ],
+      main: "readme",
+      source_url: @source_url,
+      source_ref: "master",
+      formatters: ["html"],
+      groups_for_modules: groups_for_modules(),
+      nest_modules_by_prefix: nest_modules_by_prefix()
+    ]
   end
 
   defp package do
     [
-      files: ["lib", "LICENSE*", "mix.exs", "README*"],
-      licenses: ["New BSD"],
+      description: "A Stripe client for Elixir.",
+      files: ["lib", "LICENSE*", "mix.exs", "README*", "CHANGELOG*"],
+      licenses: ["BSD-3-Clause"],
+      maintainers: [
+        "Dan Matthews",
+        "Josh Smith",
+        "Nikola Begedin",
+        "Scott Newcomer"
+      ],
       links: %{
-        "GitHub" => "https://github.com/code-corps/stripity_stripe"
-      },
-      maintainers: ["Dan Matthews", "Josh Smith", "Nikola Begedin", "Scott Newcomer"]
+        "GitHub" => @source_url
+      }
     ]
   end
 

diff --git a/mix.lock b/mix.lock
@@ -3,24 +3,24 @@
   "certifi": {:hex, :certifi, "2.6.1", "dbab8e5e155a0763eea978c913ca280a6b544bfa115633fa20249c3d396d9493", [:rebar3], [], "hexpm", "524c97b4991b3849dd5c17a631223896272c6b0af446778ba4675a1dff53bb7e"},
   "dialyxir": {:hex, :dialyxir, "1.1.0", "c5aab0d6e71e5522e77beff7ba9e08f8e02bad90dfbeffae60eaf0cb47e29488", [:mix], [{:erlex, ">= 0.2.6", [hex: :erlex, repo: "hexpm", optional: false]}], "hexpm", "07ea8e49c45f15264ebe6d5b93799d4dd56a44036cf42d0ad9c960bc266c0b9a"},
   "earmark": {:hex, :earmark, "1.3.2", "b840562ea3d67795ffbb5bd88940b1bed0ed9fa32834915125ea7d02e35888a5", [:mix], [], "hexpm", "e3be2bc3ae67781db529b80aa7e7c49904a988596e2dbff897425b48b3581161"},
-  "earmark_parser": {:hex, :earmark_parser, "1.4.13", "0c98163e7d04a15feb62000e1a891489feb29f3d10cb57d4f845c405852bbef8", [:mix], [], "hexpm", "d602c26af3a0af43d2f2645613f65841657ad6efc9f0e361c3b6c06b578214ba"},
+  "earmark_parser": {:hex, :earmark_parser, "1.4.18", "e1b2be73eb08a49fb032a0208bf647380682374a725dfb5b9e510def8397f6f2", [:mix], [], "hexpm", "114a0e85ec3cf9e04b811009e73c206394ffecfcc313e0b346de0d557774ee97"},
   "erlex": {:hex, :erlex, "0.2.6", "c7987d15e899c7a2f34f5420d2a2ea0d659682c06ac607572df55a43753aa12e", [:mix], [], "hexpm", "2ed2e25711feb44d52b17d2780eabf998452f6efda104877a3881c2f8c0c0c75"},
   "erlexec": {:hex, :erlexec, "1.9.3", "3d72ac65424ced35b9658a50e5a0c9dbd5f383e28ac9096e557f0d62926dd8e4", [:rebar3], [], "hexpm", "5e3886952e987b63d9136a0bef5ceb0091b8a0550a81d221d0e55538ee2aa1ab"},
-  "ex_doc": {:hex, :ex_doc, "0.23.0", "a069bc9b0bf8efe323ecde8c0d62afc13d308b1fa3d228b65bca5cf8703a529d", [:mix], [{:earmark_parser, "~> 1.4.0", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_elixir, "~> 0.14", [hex: :makeup_elixir, repo: "hexpm", optional: false]}], "hexpm", "f5e2c4702468b2fd11b10d39416ddadd2fcdd173ba2a0285ebd92c39827a5a16"},
+  "ex_doc": {:hex, :ex_doc, "0.26.0", "1922164bac0b18b02f84d6f69cab1b93bc3e870e2ad18d5dacb50a9e06b542a3", [:mix], [{:earmark_parser, "~> 1.4.0", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_elixir, "~> 0.14", [hex: :makeup_elixir, repo: "hexpm", optional: false]}, {:makeup_erlang, "~> 0.1", [hex: :makeup_erlang, repo: "hexpm", optional: false]}], "hexpm", "2775d66e494a9a48355db7867478ffd997864c61c65a47d31c4949459281c78d"},
   "excoveralls": {:hex, :excoveralls, "0.14.1", "14140e4ef343f2af2de33d35268c77bc7983d7824cb945e6c2af54235bc2e61f", [:mix], [{:hackney, "~> 1.16", [hex: :hackney, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: false]}], "hexpm", "4a588f9f8cf9dc140cc1f3d0ea4d849b2f76d5d8bee66b73c304bb3d3689c8b0"},
   "exexec": {:hex, :exexec, "0.1.0", "4061bffc3845cb1fcc68eb68943335c75d64cfb4b4553c78f41be457df4a8d34", [:mix], [{:erlexec, "~> 1.7", [hex: :erlexec, repo: "hexpm", optional: false]}], "hexpm", "b2a3a4bf3aadbc3b4a277cd503c25f39b5bf2bab7c8929a1c7969094b03fe4ec"},
   "hackney": {:hex, :hackney, "1.17.4", "99da4674592504d3fb0cfef0db84c3ba02b4508bae2dff8c0108baa0d6e0977c", [:rebar3], [{:certifi, "~>2.6.1", [hex: :certifi, repo: "hexpm", optional: false]}, {:idna, "~>6.1.0", [hex: :idna, repo: "hexpm", optional: false]}, {:metrics, "~>1.0.0", [hex: :metrics, repo: "hexpm", optional: false]}, {:mimerl, "~>1.1", [hex: :mimerl, repo: "hexpm", optional: false]}, {:parse_trans, "3.3.1", [hex: :parse_trans, repo: "hexpm", optional: false]}, {:ssl_verify_fun, "~>1.1.0", [hex: :ssl_verify_fun, repo: "hexpm", optional: false]}, {:unicode_util_compat, "~>0.7.0", [hex: :unicode_util_compat, repo: "hexpm", optional: false]}], "hexpm", "de16ff4996556c8548d512f4dbe22dd58a587bf3332e7fd362430a7ef3986b16"},
   "idna": {:hex, :idna, "6.1.1", "8a63070e9f7d0c62eb9d9fcb360a7de382448200fbbd1b106cc96d3d8099df8d", [:rebar3], [{:unicode_util_compat, "~>0.7.0", [hex: :unicode_util_compat, repo: "hexpm", optional: false]}], "hexpm", "92376eb7894412ed19ac475e4a86f7b413c1b9fbb5bd16dccd57934157944cea"},
   "inch_ex": {:hex, :inch_ex, "2.0.0", "24268a9284a1751f2ceda569cd978e1fa394c977c45c331bb52a405de544f4de", [:mix], [{:bunt, "~> 0.2", [hex: :bunt, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: false]}], "hexpm", "96d0ec5ecac8cf63142d02f16b7ab7152cf0f0f1a185a80161b758383c9399a8"},
   "jason": {:hex, :jason, "1.2.2", "ba43e3f2709fd1aa1dce90aaabfd039d000469c05c56f0b8e31978e03fa39052", [:mix], [{:decimal, "~> 1.0 or ~> 2.0", [hex: :decimal, repo: "hexpm", optional: true]}], "hexpm", "18a228f5f0058ee183f29f9eae0805c6e59d61c3b006760668d8d18ff0d12179"},
   "makeup": {:hex, :makeup, "1.0.5", "d5a830bc42c9800ce07dd97fa94669dfb93d3bf5fcf6ea7a0c67b2e0e4a7f26c", [:mix], [{:nimble_parsec, "~> 0.5 or ~> 1.0", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "cfa158c02d3f5c0c665d0af11512fed3fba0144cf1aadee0f2ce17747fba2ca9"},
-  "makeup_elixir": {:hex, :makeup_elixir, "0.15.1", "b5888c880d17d1cc3e598f05cdb5b5a91b7b17ac4eaf5f297cb697663a1094dd", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.1", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "db68c173234b07ab2a07f645a5acdc117b9f99d69ebf521821d89690ae6c6ec8"},
+  "makeup_elixir": {:hex, :makeup_elixir, "0.15.2", "dc72dfe17eb240552857465cc00cce390960d9a0c055c4ccd38b70629227e97c", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.1", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "fd23ae48d09b32eff49d4ced2b43c9f086d402ee4fd4fcb2d7fad97fa8823e75"},
   "makeup_erlang": {:hex, :makeup_erlang, "0.1.1", "3fcb7f09eb9d98dc4d208f49cc955a34218fc41ff6b84df7c75b3e6e533cc65f", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "174d0809e98a4ef0b3309256cbf97101c6ec01c4ab0b23e926a9e17df2077cbb"},
   "metrics": {:hex, :metrics, "1.0.1", "25f094dea2cda98213cecc3aeff09e940299d950904393b2a29d191c346a8486", [:rebar3], [], "hexpm", "69b09adddc4f74a40716ae54d140f93beb0fb8978d8636eaded0c31b6f099f16"},
   "mime": {:hex, :mime, "1.6.0", "dabde576a497cef4bbdd60aceee8160e02a6c89250d6c0b29e56c0dfb00db3d2", [:mix], [], "hexpm", "31a1a8613f8321143dde1dafc36006a17d28d02bdfecb9e95a880fa7aabd19a7"},
   "mimerl": {:hex, :mimerl, "1.2.0", "67e2d3f571088d5cfd3e550c383094b47159f3eee8ffa08e64106cdf5e981be3", [:rebar3], [], "hexpm", "f278585650aa581986264638ebf698f8bb19df297f66ad91b18910dfc6e19323"},
   "mox": {:hex, :mox, "0.4.0", "7f120840f7d626184a3d65de36189ca6f37d432e5d63acd80045198e4c5f7e6e", [:mix], [], "hexpm", "64fca8aca4699cc1acf7db19237ce781cfa46683082a440e9f4e1ac29e290d89"},
-  "nimble_parsec": {:hex, :nimble_parsec, "1.1.0", "3a6fca1550363552e54c216debb6a9e95bd8d32348938e13de5eda962c0d7f89", [:mix], [], "hexpm", "08eb32d66b706e913ff748f11694b17981c0b04a33ef470e33e11b3d3ac8f54b"},
+  "nimble_parsec": {:hex, :nimble_parsec, "1.2.0", "b44d75e2a6542dcb6acf5d71c32c74ca88960421b6874777f79153bbbbd7dccc", [:mix], [], "hexpm", "52b2871a7515a5ac49b00f214e4165a40724cf99798d8e4a65e4fd64ebd002c1"},
   "parse_trans": {:hex, :parse_trans, "3.3.1", "16328ab840cc09919bd10dab29e431da3af9e9e7e7e6f0089dd5a2d2820011d8", [:rebar3], [], "hexpm", "07cd9577885f56362d414e8c4c4e6bdf10d43a8767abb92d24cbe8b24c54888b"},
   "plug": {:hex, :plug, "1.11.1", "f2992bac66fdae679453c9e86134a4201f6f43a687d8ff1cd1b2862d53c80259", [:mix], [{:mime, "~> 1.0", [hex: :mime, repo: "hexpm", optional: false]}, {:plug_crypto, "~> 1.1.1 or ~> 1.2", [hex: :plug_crypto, repo: "hexpm", optional: false]}, {:telemetry, "~> 0.4", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm", "23524e4fefbb587c11f0833b3910bfb414bf2e2534d61928e920f54e3a1b881f"},
   "plug_crypto": {:hex, :plug_crypto, "1.2.2", "05654514ac717ff3a1843204b424477d9e60c143406aa94daf2274fdd280794d", [:mix], [], "hexpm", "87631c7ad914a5a445f0a3809f99b079113ae4ed4b867348dd9eec288cecb6db"},