From 0c29aaeb5403c4f964de04ce4b7344c8d33c65f2 Mon Sep 17 00:00:00 2001 From: Kian-Meng Ang Date: Wed, 26 Jan 2022 23:39:37 +0800 Subject: [PATCH] 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. --- .gitignore | 46 +++++++++++++++++++++--------- LICENSE => LICENSE.md | 14 +++++---- README.md | 38 ++++++++++++------------- mix.exs | 66 +++++++++++++++++++++++++------------------ mix.lock | 8 +++--- 5 files changed, 104 insertions(+), 68 deletions(-) rename LICENSE => LICENSE.md (80%) diff --git a/.gitignore b/.gitignore index a353b8c8..03f88067 100644 --- 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 b/LICENSE.md similarity index 80% rename from LICENSE rename to LICENSE.md index 04a68d87..35bcec88 100644 --- a/LICENSE +++ b/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 index 7cb092fc..08708b98 100644 --- a/README.md +++ b/README.md @@ -41,13 +41,13 @@ 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"} ``` @@ -55,7 +55,7 @@ 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,7 +75,7 @@ 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 @@ -83,7 +83,7 @@ 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 ``` @@ -91,7 +91,7 @@ config :stripity_stripe, json_library: Poison 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}] ``` @@ -99,7 +99,7 @@ config :stripity_stripe, hackney_opts: [{:connect_timeout, 1000}, {:recv_timeout 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 index e24b65b4..7d71013a 100644 --- 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 index 932866a7..65bddc4a 100644 --- a/mix.lock +++ b/mix.lock @@ -3,10 +3,10 @@ "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"}, @@ -14,13 +14,13 @@ "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"},