Skip to content

Commit 23b79dc

Browse files
kianmengprincemaple
kianmeng
and
princemaple
authored
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 <chenpaul914@gmail.com>
1 parent 4c140a6 commit 23b79dc

9 files changed

Lines changed: 138 additions & 88 deletions

File tree

‎.formatter.exs‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
# Used by "mix format"
12
[
23
inputs: ["*.{ex,exs}", "{config,lib,test}/**/*.{ex,exs}"]
34
]

‎.gitignore‎

Lines changed: 24 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,26 @@
1-
/_build
2-
/cover
3-
/deps
4-
/doc
1+
# The directory Mix will write compiled artifacts to.
2+
/_build/
3+
4+
# If you run "mix test --cover", coverage assets end up here.
5+
/cover/
6+
7+
# The directory Mix downloads your dependencies sources to.
8+
/deps/
9+
10+
# Where third-party dependencies like ExDoc output generated docs.
11+
/doc/
12+
13+
# Ignore .fetch files in case you like to edit your project deps locally.
14+
/.fetch
15+
16+
# If the VM crashes, it generates a dump, let's ignore it too.
517
erl_crash.dump
18+
19+
# Also ignore archive artifacts (built via "mix archive.build").
620
*.ez
21+
22+
# Ignore package tarball (built via "mix hex.build").
23+
phoenix_swoosh-*.tar
24+
25+
# Temporary files for e.g. tests.
26+
/tmp/

‎CHANGELOG.md‎

Lines changed: 10 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,19 @@
1-
## Changelog
1+
# Changelog
22

3-
## v0.3.2
3+
All notable changes to this project will be documented in this file.
4+
5+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7+
8+
## v0.3.2 - 2020-10-13
49

510
### Changes
611

712
### ✨ Features
813

914
- Set correct body field depending on template format @wmnnd (#154)
1015

11-
## v0.3.1
16+
## v0.3.1 - 2020-10-13
1217

1318
### Changes
1419

@@ -44,12 +49,12 @@
4449

4550
- Add support for Phoenix 1.2 release candidate.
4651

47-
## v0.1.1
52+
## v0.1.1 - 2016-04-17
4853

4954
### Fixed
5055

5156
- Add default assigns value to `render_body/3` inside the `use` macro
5257

53-
## v0.1.0
58+
## v0.1.0 - 2016-03-22
5459

5560
- Initial version

‎CONTRIBUTING.md‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
# Contributing
2+
3+
## Running tests
4+
5+
Clone the repo and fetch its dependencies:
6+
7+
```bash
8+
$ git clone https://github.com/swoosh/phoenix_swoosh.git
9+
$ cd phoenix_swoosh
10+
$ mix deps.get
11+
$ mix test
12+
```
13+
14+
## Building docs
15+
16+
Documentation is written into the library, you will find it in the source code,
17+
accessible from `iex` and of course, it all gets published to
18+
[hexdocs](http://hexdocs.pm/phoenix_swoosh).
19+
20+
```bash
21+
$ mix docs
22+
```

LICENSE.txt renamed to LICENSE.md

File renamed without changes.

‎README.md‎

Lines changed: 46 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,45 +1,68 @@
11
# Phoenix.Swoosh
22

3+
[![Elixir CI](https://github.com/swoosh/phoenix_swoosh/actions/workflows/elixir.yml/badge.svg)](https://github.com/swoosh/phoenix_swoosh/actions/workflows/elixir.yml)
4+
[![Module Version](https://img.shields.io/hexpm/v/phoenix_swoosh.svg)](https://hex.pm/packages/phoenix_swoosh)
5+
[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/phoenix_swoosh/)
6+
[![Total Download](https://img.shields.io/hexpm/dt/phoenix_swoosh.svg)](https://hex.pm/packages/phoenix_swoosh)
7+
[![License](https://img.shields.io/hexpm/l/phoenix_swoosh.svg)](https://github.com/swoosh/phoenix_swoosh/blob/master/LICENSE)
8+
[![Last Updated](https://img.shields.io/github/last-commit/swoosh/phoenix_swoosh.svg)](https://github.com/swoosh/phoenix_swoosh/commits/master)
9+
310
Use Swoosh to easily send emails in your Phoenix project.
411

512
This module provides the ability to set the HTML and/or text body of an email by rendering templates.
613

7-
See the [docs](http://hexdocs.pm/phoenix_swoosh) for more information.
8-
914
## Installation
1015

11-
Add phoenix_swoosh to your list of dependencies in `mix.exs`:
16+
Add `:phoenix_swoosh` to your list of dependencies in `mix.exs`:
1217

1318
```elixir
1419
def deps do
15-
[{:phoenix_swoosh, "~> 0.3"}]
20+
[
21+
{:phoenix_swoosh, "~> 0.3"}
22+
]
1623
end
1724
```
1825

19-
## Documentation
20-
21-
Documentation is written into the library, you will find it in the source code, accessible from `iex` and of course, it
22-
all gets published to [hexdocs](http://hexdocs.pm/phoenix_swoosh).
26+
## Usage
2327

24-
## Contributing
28+
Setting up the templates:
2529

26-
### Running tests
27-
28-
Clone the repo and fetch its dependencies:
29-
30-
```
31-
$ git clone https://github.com/swoosh/phoenix_swoosh.git
32-
$ cd phoenix_swoosh
33-
$ mix deps.get
34-
$ mix test
30+
```elixir
31+
# web/templates/layout/email.html.eex
32+
<html>
33+
<head>
34+
<title><%= @email.subject %></title>
35+
</head>
36+
<body>
37+
<%= @inner_content %>
38+
</body>
39+
</html>
40+
41+
# web/templates/email/welcome.html.eex
42+
<div>
43+
<h1>Welcome to Sample, <%= @username %>!</h1>
44+
</div>
3545
```
3646

37-
### Building docs
47+
Passing values to templates:
3848

49+
```elixir
50+
# web/emails/user_email.ex
51+
defmodule Sample.UserEmail do
52+
use Phoenix.Swoosh, view: Sample.EmailView, layout: {Sample.LayoutView, :email}
53+
54+
def welcome(user) do
55+
new()
56+
|> from("tony@stark.com")
57+
|> to(user.email)
58+
|> subject("Hello, Avengers!")
59+
|> render_body("welcome.html", %{username: user.email})
60+
end
61+
end
3962
```
40-
$ MIX_ENV=docs mix docs
41-
```
4263

43-
## LICENSE
64+
## Copyright and License
65+
66+
Copyright (c) 2016 Swoosh contributors
4467

45-
See [LICENSE](https://github.com/swoosh/phoenix_swoosh/blob/main/LICENSE.txt)
68+
Released under the MIT License, which can be found in [LICENSE.md](./LICENSE.md).

‎lib/phoenix_swoosh.ex‎

Lines changed: 7 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -4,36 +4,6 @@ defmodule Phoenix.Swoosh do
44
text body of an email by rendering templates.
55
66
It has been designed to integrate with Phoenix view, template and layout system.
7-
8-
## Example
9-
10-
# web/templates/layout/email.html.eex
11-
<html>
12-
<head>
13-
<title><%= @email.subject %></title>
14-
</head>
15-
<body>
16-
<%= @inner_content %>
17-
</body>
18-
</html>
19-
20-
# web/templates/email/welcome.html.eex
21-
<div>
22-
<h1>Welcome to Sample, <%= @username %>!</h1>
23-
</div>
24-
25-
# web/emails/user_email.ex
26-
defmodule Sample.UserEmail do
27-
use Phoenix.Swoosh, view: Sample.EmailView, layout: {Sample.LayoutView, :email}
28-
29-
def welcome(user) do
30-
new()
31-
|> from("tony@stark.com")
32-
|> to(user.email)
33-
|> subject("Hello, Avengers!")
34-
|> render_body("welcome.html", %{username: user.email})
35-
end
36-
end
377
"""
388

399
import Swoosh.Email
@@ -63,13 +33,14 @@ defmodule Phoenix.Swoosh do
6333
@doc """
6434
Renders the given `template` and `assigns` based on the `email`.
6535
66-
Once the template is rendered the resulting string is stored on the email fields `html_body` and `text_body` depending
67-
on the format of the template.
68-
`.html`, `.htm`, and `.xml` are stored in `html_body`; all other extensions, (e.g. `.txt` and `.text`), in `text_body`.
36+
Once the template is rendered the resulting string is stored on the email
37+
fields `html_body` and `text_body` depending on the format of the template.
38+
`.html`, `.htm`, and `.xml` are stored in `html_body`; all other extensions,
39+
(e.g. `.txt` and `.text`), in `text_body`.
6940
7041
## Arguments
7142
72-
* `email` - the `Swoosh.Email` struct
43+
* `email` - the `Swoosh.Email` struct.
7344
7445
* `template` - may be an atom or a string. If an atom, like `:welcome`, it
7546
will render both the HTML and text template and stores them respectively on
@@ -80,7 +51,7 @@ defmodule Phoenix.Swoosh do
8051
assigns are merged and have higher order precedence than the email assigns.
8152
(`email.assigns`)
8253
83-
## Example
54+
## Examples
8455
8556
defmodule Sample.UserEmail do
8657
use Phoenix.Swoosh, view: Sample.EmailView
@@ -191,6 +162,7 @@ defmodule Phoenix.Swoosh do
191162
iex> email = put_layout email, :email
192163
iex> layout(email)
193164
{AppView, :email}
165+
194166
"""
195167
def put_layout(email, layout) do
196168
do_put_layout(email, layout)

‎mix.exs‎

Lines changed: 27 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,22 @@
11
defmodule PhoenixSwoosh.Mixfile do
22
use Mix.Project
33

4+
@source_url "https://github.com/swoosh/phoenix_swoosh"
45
@version "0.3.2"
56

67
def project do
78
[
89
app: :phoenix_swoosh,
910
version: @version,
1011
elixir: "~> 1.8",
12+
name: "Phoenix.Swoosh",
1113
compilers: compilers(Mix.env()),
1214
build_embedded: Mix.env() == :prod,
1315
start_permanent: Mix.env() == :prod,
1416
deps: deps(),
15-
16-
# Hex
17-
description: description(),
1817
package: package(),
19-
20-
# Docs
21-
name: "Phoenix.Swoosh",
22-
docs: [
23-
source_ref: "v#{@version}",
24-
main: "Phoenix.Swoosh",
25-
canonical: "http://hexdocs.pm/phoenix_swoosh",
26-
source_url: "https://github.com/swoosh/phoenix_swoosh"
27-
]
18+
docs: docs(),
19+
preferred_cli_env: [docs: :docs]
2820
]
2921
end
3022

@@ -42,21 +34,36 @@ defmodule PhoenixSwoosh.Mixfile do
4234
{:phoenix_html, "~> 2.14"},
4335
{:hackney, "~> 1.9"},
4436
{:credo, "~> 1.0", only: [:dev, :test]},
45-
{:ex_doc, "~> 0.22", only: :docs}
37+
{:ex_doc, ">= 0.0.0", only: :docs, runtime: false}
4638
]
4739
end
4840

49-
defp description do
50-
"""
51-
Use Swoosh to easily send emails in your Phoenix project.
52-
"""
53-
end
54-
5541
defp package do
5642
[
43+
description: "Use Swoosh to easily send emails in your Phoenix project.",
5744
maintainers: ["Steve Domin", "Po Chen"],
5845
licenses: ["MIT"],
59-
links: %{"GitHub" => "https://github.com/swoosh/phoenix_swoosh"}
46+
links: %{
47+
"Changelog" => "https://hexdocs.pm/phoenix_swoosh/changelog.html",
48+
"GitHub" => @source_url
49+
}
50+
]
51+
end
52+
53+
defp docs do
54+
[
55+
extras: [
56+
"CHANGELOG.md",
57+
"CONTRIBUTING.md",
58+
"LICENSE.md": [title: "License"],
59+
"README.md": [title: "Overview"]
60+
],
61+
main: "readme",
62+
canonical: "http://hexdocs.pm/phoenix_swoosh",
63+
source_url: @source_url,
64+
source_ref: "v#{@version}",
65+
api_reference: false,
66+
formatters: ["html"]
6067
]
6168
end
6269
end

‎mix.lock‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@
33
"certifi": {:hex, :certifi, "2.6.1", "dbab8e5e155a0763eea978c913ca280a6b544bfa115633fa20249c3d396d9493", [:rebar3], [], "hexpm", "524c97b4991b3849dd5c17a631223896272c6b0af446778ba4675a1dff53bb7e"},
44
"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"},
55
"earmark_parser": {:hex, :earmark_parser, "1.4.12", "b245e875ec0a311a342320da0551da407d9d2b65d98f7a9597ae078615af3449", [:mix], [], "hexpm", "711e2cc4d64abb7d566d43f54b78f7dc129308a63bc103fbd88550d2174b3160"},
6-
"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"},
6+
"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"},
77
"file_system": {:hex, :file_system, "0.2.10", "fb082005a9cd1711c05b5248710f8826b02d7d1784e7c3451f9c1231d4fc162d", [:mix], [], "hexpm", "41195edbfb562a593726eda3b3e8b103a309b733ad25f3d642ba49696bf715dc"},
88
"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"},
99
"idna": {:hex, :idna, "6.1.1", "8a63070e9f7d0c62eb9d9fcb360a7de382448200fbbd1b106cc96d3d8099df8d", [:rebar3], [{:unicode_util_compat, "~>0.7.0", [hex: :unicode_util_compat, repo: "hexpm", optional: false]}], "hexpm", "92376eb7894412ed19ac475e4a86f7b413c1b9fbb5bd16dccd57934157944cea"},

0 commit comments

Comments
 (0)