Misc doc changes (#39)

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.
pablo-co · Jun 21, 2021 · c8b8cbf · c8b8cbf
1 parent e25fbec
commit c8b8cbf
Show file tree

Hide file tree

Showing 9 changed files with 123 additions and 60 deletions.
diff --git a/.formatter.exs b/.formatter.exs
@@ -0,0 +1,4 @@
+# Used by "mix format"
+[
+  inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}"]
+]
diff --git a/.gitignore b/.gitignore
@@ -1,17 +1,26 @@
 # The directory Mix will write compiled artifacts to.
-/_build
+/_build/
 
 # If you run "mix test --cover", coverage assets end up here.
-/cover
+/cover/
 
 # The directory Mix downloads your dependencies sources to.
-/deps
+/deps/
 
-# Where 3rd-party dependencies like ExDoc output generated docs.
-/doc
+# 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
+
+# Ignore package tarball (built via "mix hex.build").
+bamboo_postmark-*.tar
+
+# Temporary files, for example, from tests.
+/tmp/
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,42 +1,49 @@
-## 1.0.0
+# 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).
+
+## v1.0.0 - 2021-04-30
 
 ### Changes
 * Change return of deliver/2 to work with Bamboo v2.0
 * Require Bamboo 2.0.0 or above
 
-## 0.7.0
+## v0.7.0 - 2020-12-13
 
 ### Fixes/Enhancements
 
 * Support inline attachments ([#34])
 
 [#34]: https://github.com/pablo-co/bamboo_postmark/pull/34
 
-## 0.6.1
+## v0.6.1 - 2020-12-13
 
 ### Fixes/Enhancements
 
 * Pass attachments as params to Postmark ([#31])
 
 [#31]: https://github.com/pablo-co/bamboo_postmark/pull/31
 
-## 0.6.0
+## v0.6.0 - 2019-06-19
 
 ### New Additions
 
 * Allow configuring API key with {:system, "ENVVAR"} ([#26])
 
 [#26]: https://github.com/pablo-co/bamboo_postmark/pull/26
 
-## 0.5.0
+## v0.5.0 - 2019-02-11
 
 ### New Additions
 
 * Make JSON library configurable ([#22])
 
 [#22]: https://github.com/pablo-co/bamboo_postmark/pull/22
 
-## 0.4.2
+## v0.4.2 - 2018-01-23
 
 ### Fixes/Enhancements
 
@@ -48,23 +55,23 @@
 [#17]: https://github.com/pablo-co/bamboo_postmark/pull/17
 [#18]: https://github.com/pablo-co/bamboo_postmark/pull/18
 
-## 0.4.1
+## v0.4.1 - 2017-06-07
 
 ### Fixes/Enhancements
 
 * Return body in response of PostmarkAdapter.deliver ([#14])
 
 [#14]: https://github.com/pablo-co/bamboo_postmark/pull/14
 
-## 0.4.0
+## v0.4.0 - 2017-05-23
 
 ### New Additions
 
 * Allow configuration of request options ([#12])
 
 [#12]: https://github.com/pablo-co/bamboo_postmark/pull/12
 
-## 0.3.0
+## v0.3.0 - 2017-05-06
 
 ### New Additions
 
@@ -77,7 +84,7 @@
 [#9]: https://github.com/pablo-co/bamboo_postmark/pull/9
 [#7]: https://github.com/pablo-co/bamboo_postmark/pull/7
 
-## 0.2.0
+## v0.2.0 - 2016-12-29
 
 ### New Additions
 
@@ -89,3 +96,7 @@
 
 [#5]: https://github.com/pablo-co/bamboo_postmark/pull/5
 [#6]: https://github.com/pablo-co/bamboo_postmark/pull/6
+
+## v0.1.0 - 2016-09-02
+
+* Initial public release.
diff --git a/LICENSE → LICENSE.md b/LICENSE → LICENSE.md
diff --git a/README.md b/README.md
@@ -1,27 +1,35 @@
 # Bamboo.PostmarkAdapter
 
 [![CircleCI](https://circleci.com/gh/pablo-co/bamboo_postmark.svg?style=svg)](https://circleci.com/gh/pablo-co/bamboo_postmark)
+[![Module Version](https://img.shields.io/hexpm/v/bamboo_postmark.svg)](https://hex.pm/packages/bamboo_postmark)
+[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/bamboo_postmark/)
+[![Total Download](https://img.shields.io/hexpm/dt/bamboo_postmark.svg)](https://hex.pm/packages/bamboo_postmark)
+[![License](https://img.shields.io/hexpm/l/bamboo_postmark.svg)](https://github.com/pablo-co/bamboo_postmark/blob/master/LICENSE.md)
+[![Last Updated](https://img.shields.io/github/last-commit/pablo-co/bamboo_postmark.svg)](https://github.com/pablo-co/bamboo_postmark/commits/master)
 
-A [Postmark](https://postmarkapp.com/) Adapter for the [Bamboo](https://github.com/thoughtbot/bamboo) email library.
+A [Postmark](https://postmarkapp.com/) adapter for the [Bamboo](https://github.com/thoughtbot/bamboo) email library.
 
 ## Installation
 
-The package can be installed as:
-
-1. Add bamboo_postmark to your list of dependencies in `mix.exs`:
+The package can be installed by adding `:bamboo_postmark` to your list of
+dependencies in `mix.exs`:
 
 ```elixir
 def deps do
   # Get from hex
-  [{:bamboo_postmark, "~> 1.0"}]
+  [
+    {:bamboo_postmark, "~> 1.0"}
+  ]
+
   # Or use the latest from master
-  [{:bamboo_postmark, github: "pablo-co/bamboo_postmark"}]
+  [
+    {:bamboo_postmark, github: "pablo-co/bamboo_postmark"}
+  ]
 end
 ```
 
-2. Add your Postmark API key to your config
-
-> You can find this key as `Server API token` under the `Credentials` tab in each Postmark server.
+Add your Postmark API key to your config. You can find this key as `Server API
+token` under the `Credentials` tab in each Postmark server.
 
 ```elixir
 # In your configuration file:
@@ -35,15 +43,13 @@ config :my_app, MyApp.Mailer,
       # api_key: {:system, "POSTMARK_API_KEY"}
 ```
 
-3. Follow Bamboo [Getting Started Guide](https://github.com/thoughtbot/bamboo#getting-started)
+Follow Bamboo [Getting Started Guide](https://github.com/thoughtbot/bamboo#getting-started).
 
 ## Using templates
 
 The Postmark adapter provides a helper module for setting the template of an
 email.
 
-### Example
-
 ```elixir
 defmodule MyApp.Mail do
   import Bamboo.PostmarkHelper
@@ -72,8 +78,6 @@ email
 
 The Postmark adapter provides a helper module for tagging emails.
 
-### Example
-
 ```elixir
 defmodule MyApp.Mail do
   import Bamboo.PostmarkHelper
@@ -89,7 +93,7 @@ end
 
 You can send other extra parameters to Postmark with the `put_param` helper.
 
-> See Postmark's API for a complete list of parameters supported.
+See Postmark's API for a complete list of parameters supported.
 
 ```elixir
 email
@@ -122,3 +126,9 @@ config :my_app, MyApp.Mailer,
 ## JSON support
 
 Bamboo comes with JSON support out of the box, see [Bamboo JSON support](https://github.com/thoughtbot/bamboo#json-support).
+
+## Copyright and License
+
+Copyright (c) 2016 Pablo Cárdenas
+
+This library is released under the MIT License. See the [LICENSE.md](./LICENSE.md) file.
diff --git a/lib/bamboo/postmark_adapter.ex b/lib/bamboo/postmark_adapter.ex
@@ -5,12 +5,13 @@ defmodule Bamboo.PostmarkAdapter do
   Use this adapter to send emails through Postmark's API. Requires that an API
   key is set in the config.
 
-  ## Example config
+  ## Example
 
       # In config/config.exs, or config.prod.exs, etc.
       config :my_app, MyApp.Mailer,
         adapter: Bamboo.PostmarkAdapter,
         api_key: "my_api_key" or {:system, "POSTMARK_API_KEY"}
+
   """
 
   @behaviour Bamboo.Adapter
@@ -192,5 +193,4 @@ defmodule Bamboo.PostmarkAdapter do
   defp options(config) do
     Keyword.merge(config[:request_options] || [], [with_body: true])
   end
-
 end
diff --git a/lib/bamboo/postmark_helper.ex b/lib/bamboo/postmark_helper.ex
@@ -1,6 +1,6 @@
 defmodule Bamboo.PostmarkHelper do
   @moduledoc """
-  Functions for using features specific to Postmark e.g. templates
+  Functions for using features specific to Postmark's templates.
   """
 
   alias Bamboo.Email
@@ -10,9 +10,11 @@ defmodule Bamboo.PostmarkHelper do
   and get detailed statistics.
 
   A convenience function for `put_private(email, :tag, "my-tag")`
-  ## Example
+
+  ## Examples
 
       tag(email, "welcome-email")
+
   """
   def tag(email, tag) do
     Email.put_private(email, :tag, tag)
@@ -26,10 +28,11 @@ defmodule Bamboo.PostmarkHelper do
   template id specified here must match the template id in Postmark.
   Postmarks's API docs for this can be found [here](https://postmarkapp.com/developer/api/templates-api#email-with-template).
 
-  ## Example
+  ## Examples
 
       template(email, "9746128")
       template(email, "9746128", %{"name" => "Name", "content" => "John"})
+
   """
   def template(email, template_id, template_model \\ %{}) do
     email
@@ -41,7 +44,7 @@ defmodule Bamboo.PostmarkHelper do
   Put extra message parameters that are used by Postmark. You can set things
   like TrackOpens, TrackLinks or Attachments.
 
-  ## Example
+  ## Examples
 
       put_param(email, "TrackLinks", "HtmlAndText")
       put_param(email, "TrackOpens", true)
@@ -52,6 +55,7 @@ defmodule Bamboo.PostmarkHelper do
           ContentType: "txt"
         }
       ])
+
   """
   def put_param(%Email{private: %{message_params: _}} = email, key, value) do
     put_in(email.private[:message_params][key], value)

diff --git a/mix.exs b/mix.exs
@@ -1,40 +1,63 @@
 defmodule BambooPostmark.Mixfile do
   use Mix.Project
 
-  @project_url "https://github.com/pablo-co/bamboo_postmark"
+  @source_url "https://github.com/pablo-co/bamboo_postmark"
+  @version "1.0.0"
 
   def project do
-    [app: :bamboo_postmark,
-     version: "1.0.0",
-     elixir: "~> 1.4",
-     source_url: @project_url,
-     homepage_url: @project_url,
-     name: "Bamboo Postmark Adapter",
-     description: "A Bamboo adapter for Postmark",
-     build_embedded: Mix.env == :prod,
-     start_permanent: Mix.env == :prod,
-     package: package(),
-     deps: deps()]
+    [
+      app: :bamboo_postmark,
+      version: @version,
+      elixir: "~> 1.4",
+      name: "Bamboo Postmark",
+      build_embedded: Mix.env() == :prod,
+      start_permanent: Mix.env() == :prod,
+      package: package(),
+      deps: deps(),
+      docs: docs()
+    ]
   end
 
   def application do
-    [extra_applications: [:logger]]
+    [
+      extra_applications: [:logger]
+    ]
   end
 
   defp deps do
-    [{:bamboo, ">= 2.0.0"},
-     {:hackney, ">= 1.6.5"},
-     {:poison, ">= 1.5.0", only: :test},
-     {:plug, "~> 1.0"},
-     {:plug_cowboy, "~> 1.0", only: [:test, :dev]},
-     {:ex_doc, "~> 0.19", only: :dev}]
+    [
+      {:bamboo, ">= 2.0.0"},
+      {:hackney, ">= 1.6.5"},
+      {:poison, ">= 1.5.0", only: :test},
+      {:plug, "~> 1.0"},
+      {:plug_cowboy, "~> 1.0", only: [:test, :dev]},
+      {:ex_doc, "> 0.0.0", only: :dev, runtime: false}
+    ]
   end
 
   defp package do
     [
+      description: "A Bamboo adapter for Postmark",
       maintainers: ["Pablo Cárdenas"],
       licenses: ["MIT"],
-      links: %{"GitHub" => @project_url}
+      links: %{
+        "Changelog" => "https://hexdocs.pm/bamboo/postmark/changelog.html",
+        "GitHub" => @source_url
+      }
+    ]
+  end
+
+  defp docs do
+    [
+      extras: [
+        "CHANGELOG.md": [title: "Changelog"],
+        "LICENSE.md": [title: "License"],
+        "README.md": [title: "Overview"]
+      ],
+      main: "readme",
+      source_url: @source_url,
+      homepage_url: @source_url,
+      formatters: ["html"]
     ]
   end
 end