Misc doc changes (#186)

* Misc doc changes Besides other documentation changes, this commit ensures the generated HTML doc for HexDocs.pm will become the main source doc for this Elixir library which leverage on latest ExDoc features. * Update .formatter.exs Co-authored-by: Po Chen <[email protected]>
swoosh · Apr 4, 2021 · 23b79dc · 23b79dc
1 parent 4c140a6
commit 23b79dc
Show file tree

Hide file tree

Showing 9 changed files with 138 additions and 88 deletions.
diff --git a/.formatter.exs b/.formatter.exs
@@ -1,3 +1,4 @@
+# Used by "mix format"
 [
   inputs: ["*.{ex,exs}", "{config,lib,test}/**/*.{ex,exs}"]
 ]
diff --git a/.gitignore b/.gitignore
@@ -1,6 +1,26 @@
-/_build
-/cover
-/deps
-/doc
+# 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
+
+# Ignore package tarball (built via "mix hex.build").
+phoenix_swoosh-*.tar
+
+# Temporary files for e.g. tests.
+/tmp/
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,14 +1,19 @@
-## Changelog
+# Changelog
 
-## v0.3.2
+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.3.2 - 2020-10-13
 
 ### Changes
 
 ### ✨ Features
 
 - Set correct body field depending on template format @wmnnd (#154)
 
-## v0.3.1
+## v0.3.1 - 2020-10-13
 
 ### Changes
 
@@ -44,12 +49,12 @@
 
 - Add support for Phoenix 1.2 release candidate.
 
-## v0.1.1
+## v0.1.1 - 2016-04-17
 
 ### Fixed
 
 - Add default assigns value to `render_body/3` inside the `use` macro
 
-## v0.1.0
+## v0.1.0 - 2016-03-22
 
 - Initial version
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,22 @@
+# Contributing
+
+## Running tests
+
+Clone the repo and fetch its dependencies:
+
+```bash
+$ git clone https://github.com/swoosh/phoenix_swoosh.git
+$ cd phoenix_swoosh
+$ mix deps.get
+$ mix test
+```
+
+## Building docs
+
+Documentation is written into the library, you will find it in the source code,
+accessible from `iex` and of course, it all gets published to
+[hexdocs](http://hexdocs.pm/phoenix_swoosh).
+
+```bash
+$ mix docs
+```
diff --git a/LICENSE.txt → LICENSE.md b/LICENSE.txt → LICENSE.md
diff --git a/README.md b/README.md
@@ -1,45 +1,68 @@
 # Phoenix.Swoosh
 
+[![Elixir CI](https://github.com/swoosh/phoenix_swoosh/actions/workflows/elixir.yml/badge.svg)](https://github.com/swoosh/phoenix_swoosh/actions/workflows/elixir.yml)
+[![Module Version](https://img.shields.io/hexpm/v/phoenix_swoosh.svg)](https://hex.pm/packages/phoenix_swoosh)
+[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/phoenix_swoosh/)
+[![Total Download](https://img.shields.io/hexpm/dt/phoenix_swoosh.svg)](https://hex.pm/packages/phoenix_swoosh)
+[![License](https://img.shields.io/hexpm/l/phoenix_swoosh.svg)](https://github.com/swoosh/phoenix_swoosh/blob/master/LICENSE)
+[![Last Updated](https://img.shields.io/github/last-commit/swoosh/phoenix_swoosh.svg)](https://github.com/swoosh/phoenix_swoosh/commits/master)
+
 Use Swoosh to easily send emails in your Phoenix project.
 
 This module provides the ability to set the HTML and/or text body of an email by rendering templates.
 
-See the [docs](http://hexdocs.pm/phoenix_swoosh) for more information.
-
 ## Installation
 
-Add phoenix_swoosh to your list of dependencies in `mix.exs`:
+Add `:phoenix_swoosh` to your list of dependencies in `mix.exs`:
 
 ```elixir
 def deps do
-  [{:phoenix_swoosh, "~> 0.3"}]
+  [
+    {:phoenix_swoosh, "~> 0.3"}
+  ]
 end
 ```
 
-## Documentation
-
-Documentation is written into the library, you will find it in the source code, accessible from `iex` and of course, it
-all gets published to [hexdocs](http://hexdocs.pm/phoenix_swoosh).
+## Usage
 
-## Contributing
+Setting up the templates:
 
-### Running tests
-
-Clone the repo and fetch its dependencies:
-
-```
-$ git clone https://github.com/swoosh/phoenix_swoosh.git
-$ cd phoenix_swoosh
-$ mix deps.get
-$ mix test
+```elixir
+# web/templates/layout/email.html.eex
+<html>
+  <head>
+    <title><%= @email.subject %></title>
+  </head>
+  <body>
+    <%= @inner_content %>
+  </body>
+</html>
+
+# web/templates/email/welcome.html.eex
+<div>
+  <h1>Welcome to Sample, <%= @username %>!</h1>
+</div>
 ```
 
-### Building docs
+Passing values to templates:
 
+```elixir
+# web/emails/user_email.ex
+defmodule Sample.UserEmail do
+  use Phoenix.Swoosh, view: Sample.EmailView, layout: {Sample.LayoutView, :email}
+
+  def welcome(user) do
+    new()
+    |> from("[email protected]")
+    |> to(user.email)
+    |> subject("Hello, Avengers!")
+    |> render_body("welcome.html", %{username: user.email})
+  end
+end
 ```
-$ MIX_ENV=docs mix docs
-```
 
-## LICENSE
+## Copyright and License
+
+Copyright (c) 2016 Swoosh contributors
 
-See [LICENSE](https://github.com/swoosh/phoenix_swoosh/blob/main/LICENSE.txt)
+Released under the MIT License, which can be found in [LICENSE.md](./LICENSE.md).
diff --git a/lib/phoenix_swoosh.ex b/lib/phoenix_swoosh.ex
@@ -4,36 +4,6 @@ defmodule Phoenix.Swoosh do
   text body of an email by rendering templates.
 
   It has been designed to integrate with Phoenix view, template and layout system.
-
-  ## Example
-
-      # web/templates/layout/email.html.eex
-      <html>
-        <head>
-          <title><%= @email.subject %></title>
-        </head>
-        <body>
-          <%= @inner_content %>
-        </body>
-      </html>
-
-      # web/templates/email/welcome.html.eex
-      <div>
-        <h1>Welcome to Sample, <%= @username %>!</h1>
-      </div>
-
-      # web/emails/user_email.ex
-      defmodule Sample.UserEmail do
-        use Phoenix.Swoosh, view: Sample.EmailView, layout: {Sample.LayoutView, :email}
-
-        def welcome(user) do
-          new()
-          |> from("[email protected]")
-          |> to(user.email)
-          |> subject("Hello, Avengers!")
-          |> render_body("welcome.html", %{username: user.email})
-        end
-      end
   """
 
   import Swoosh.Email
@@ -63,13 +33,14 @@ defmodule Phoenix.Swoosh do
   @doc """
   Renders the given `template` and `assigns` based on the `email`.
 
-  Once the template is rendered the resulting string is stored on the email fields `html_body` and `text_body` depending
-  on the format of the template.
-  `.html`, `.htm`, and `.xml` are stored in `html_body`; all other extensions, (e.g. `.txt` and `.text`), in `text_body`.
+  Once the template is rendered the resulting string is stored on the email
+  fields `html_body` and `text_body` depending on the format of the template.
+  `.html`, `.htm`, and `.xml` are stored in `html_body`; all other extensions,
+  (e.g. `.txt` and `.text`), in `text_body`.
 
   ## Arguments
 
-    * `email` - the `Swoosh.Email` struct
+    * `email` - the `Swoosh.Email` struct.
 
     * `template` - may be an atom or a string. If an atom, like `:welcome`, it
       will render both the HTML and text template and stores them respectively on
@@ -80,7 +51,7 @@ defmodule Phoenix.Swoosh do
       assigns are merged and have higher order precedence than the email assigns.
       (`email.assigns`)
 
-  ## Example
+  ## Examples
 
       defmodule Sample.UserEmail do
         use Phoenix.Swoosh, view: Sample.EmailView
@@ -191,6 +162,7 @@ defmodule Phoenix.Swoosh do
       iex> email = put_layout email, :email
       iex> layout(email)
       {AppView, :email}
+
   """
   def put_layout(email, layout) do
     do_put_layout(email, layout)

diff --git a/mix.exs b/mix.exs
@@ -1,30 +1,22 @@
 defmodule PhoenixSwoosh.Mixfile do
   use Mix.Project
 
+  @source_url "https://github.com/swoosh/phoenix_swoosh"
   @version "0.3.2"
 
   def project do
     [
       app: :phoenix_swoosh,
       version: @version,
       elixir: "~> 1.8",
+      name: "Phoenix.Swoosh",
       compilers: compilers(Mix.env()),
       build_embedded: Mix.env() == :prod,
       start_permanent: Mix.env() == :prod,
       deps: deps(),
-
-      # Hex
-      description: description(),
       package: package(),
-
-      # Docs
-      name: "Phoenix.Swoosh",
-      docs: [
-        source_ref: "v#{@version}",
-        main: "Phoenix.Swoosh",
-        canonical: "http://hexdocs.pm/phoenix_swoosh",
-        source_url: "https://github.com/swoosh/phoenix_swoosh"
-      ]
+      docs: docs(),
+      preferred_cli_env: [docs: :docs]
     ]
   end
 
@@ -42,21 +34,36 @@ defmodule PhoenixSwoosh.Mixfile do
       {:phoenix_html, "~> 2.14"},
       {:hackney, "~> 1.9"},
       {:credo, "~> 1.0", only: [:dev, :test]},
-      {:ex_doc, "~> 0.22", only: :docs}
+      {:ex_doc, ">= 0.0.0", only: :docs, runtime: false}
     ]
   end
 
-  defp description do
-    """
-    Use Swoosh to easily send emails in your Phoenix project.
-    """
-  end
-
   defp package do
     [
+      description: "Use Swoosh to easily send emails in your Phoenix project.",
       maintainers: ["Steve Domin", "Po Chen"],
       licenses: ["MIT"],
-      links: %{"GitHub" => "https://github.com/swoosh/phoenix_swoosh"}
+      links: %{
+        "Changelog" => "https://hexdocs.pm/phoenix_swoosh/changelog.html",
+        "GitHub" => @source_url
+      }
+    ]
+  end
+
+  defp docs do
+    [
+      extras: [
+        "CHANGELOG.md",
+        "CONTRIBUTING.md",
+        "LICENSE.md": [title: "License"],
+        "README.md": [title: "Overview"]
+      ],
+      main: "readme",
+      canonical: "http://hexdocs.pm/phoenix_swoosh",
+      source_url: @source_url,
+      source_ref: "v#{@version}",
+      api_reference: false,
+      formatters: ["html"]
     ]
   end
 end
diff --git a/mix.lock b/mix.lock
@@ -3,7 +3,7 @@
   "certifi": {:hex, :certifi, "2.6.1", "dbab8e5e155a0763eea978c913ca280a6b544bfa115633fa20249c3d396d9493", [:rebar3], [], "hexpm", "524c97b4991b3849dd5c17a631223896272c6b0af446778ba4675a1dff53bb7e"},
   "credo": {:hex, :credo, "1.5.5", "e8f422026f553bc3bebb81c8e8bf1932f498ca03339856c7fec63d3faac8424b", [:mix], [{:bunt, "~> 0.2.0", [hex: :bunt, repo: "hexpm", optional: false]}, {:file_system, "~> 0.2.8", [hex: :file_system, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: false]}], "hexpm", "dd8623ab7091956a855dc9f3062486add9c52d310dfd62748779c4315d8247de"},
   "earmark_parser": {:hex, :earmark_parser, "1.4.12", "b245e875ec0a311a342320da0551da407d9d2b65d98f7a9597ae078615af3449", [:mix], [], "hexpm", "711e2cc4d64abb7d566d43f54b78f7dc129308a63bc103fbd88550d2174b3160"},
-  "ex_doc": {:hex, :ex_doc, "0.24.0", "2df14354835afaabdf87cb2971ea9485d8a36ff590e4b6c250b4f60c8fdf9143", [: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", "a0f4bcff21ceebea48414e49885d2a3e542200f76a2facf3f8faa54935eeb721"},
+  "ex_doc": {:hex, :ex_doc, "0.24.1", "15673de99154f93ca7f05900e4e4155ced1ee0cd34e0caeee567900a616871a4", [: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", "07972f17bdf7dc7b5bd76ec97b556b26178ed3f056e7ec9288eb7cea7f91cce2"},
   "file_system": {:hex, :file_system, "0.2.10", "fb082005a9cd1711c05b5248710f8826b02d7d1784e7c3451f9c1231d4fc162d", [:mix], [], "hexpm", "41195edbfb562a593726eda3b3e8b103a309b733ad25f3d642ba49696bf715dc"},
   "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"},