Skip to content

Commit e876b4f

Browse files
achempionachempion
committed
Move documentation to README.md
1 parent f2a7b86 commit e876b4f

File tree

2 files changed

+112
-113
lines changed

2 files changed

+112
-113
lines changed

‎README.md

+111
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,117 @@ Waffle is a flexible file upload library for Elixir with straightforward integra
2020

2121
[Documentation](https://hexdocs.pm/waffle)
2222

23+
## Installation
24+
25+
Add the latest stable release to your `mix.exs` file, along with the
26+
required dependencies for `ExAws` if appropriate:
27+
28+
```elixir
29+
defp deps do
30+
[
31+
{:waffle, "~> 1.1"},
32+
33+
# If using S3:
34+
{:ex_aws, "~> 2.1.2"},
35+
{:ex_aws_s3, "~> 2.0"},
36+
{:hackney, "~> 1.9"},
37+
{:sweet_xml, "~> 0.6"}
38+
]
39+
end
40+
```
41+
42+
Then run `mix deps.get` in your shell to fetch the dependencies.
43+
44+
## Usage
45+
46+
After installing Waffle, another two things should be done:
47+
48+
1. setup a storage provider
49+
2. define a definition module
50+
51+
### Setup a storage provider
52+
53+
Waffle has two built-in storage providers:
54+
55+
* `Waffle.Storage.Local`
56+
* `Waffle.Storage.S3`
57+
58+
[Other available storage providers](#other-storage-providers)
59+
are supported by the community.
60+
61+
An example for setting up `Waffle.Storage.Local`:
62+
63+
```elixir
64+
config :waffle,
65+
storage: Waffle.Storage.Local,
66+
asset_host: "http://static.example.com" # or {:system, "ASSET_HOST"}
67+
```
68+
69+
An example for setting up `Waffle.Storage.S3`:
70+
71+
```elixir
72+
config :waffle,
73+
storage: Waffle.Storage.S3,
74+
bucket: "custom_bucket", # or {:system, "AWS_S3_BUCKET"}
75+
asset_host: "http://static.example.com" # or {:system, "ASSET_HOST"}
76+
77+
config :ex_aws,
78+
json_codec: Jason
79+
# any configurations provided by https://github.com/ex-aws/ex_aws
80+
```
81+
82+
### Define a definition module
83+
84+
Waffle requires a **definition module** which contains the relevant
85+
functions to store and retrieve files:
86+
87+
* Optional transformations of the uploaded file
88+
* Where to put your files (the storage directory)
89+
* How to name your files
90+
* How to secure your files (private? Or publicly accessible?)
91+
* Default placeholders
92+
93+
This module can be created manually or generated by `mix waffle.g`
94+
automatically.
95+
96+
As an example, we will generate a definition module for handling
97+
avatars:
98+
99+
mix waffle.g avatar
100+
101+
This should generate a file at `lib/[APP_NAME]_web/uploaders/avatar.ex`.
102+
Check this file for descriptions of configurable options.
103+
104+
## Examples
105+
106+
* [An example for Local storage driver](documentation/examples/local.md)
107+
* [An example for S3 storage driver](documentation/examples/s3.md)
108+
109+
## Usage with Ecto
110+
111+
Waffle comes with a companion package for use with Ecto. If you
112+
intend to use Waffle with Ecto, it is highly recommended you also
113+
add the
114+
[`waffle_ecto`](https://github.com/elixir-waffle/waffle_ecto)
115+
dependency. Benefits include:
116+
117+
* Changeset integration
118+
* Versioned urls for cache busting (`.../thumb.png?v=63601457477`)
119+
120+
## Other Storage Providers
121+
122+
* **Rackspace** - [arc_rackspace](https://github.com/lokalebasen/arc_rackspace)
123+
124+
* **Manta** - [arc_manta](https://github.com/onyxrev/arc_manta)
125+
126+
* **OVH** - [arc_ovh](https://github.com/stephenmoloney/arc_ovh)
127+
128+
* **Google Cloud Storage** - [waffle_gcs](https://github.com/kolorahl/waffle_gcs)
129+
130+
* **Microsoft Azure Storage** - [arc_azure](https://github.com/phil-a/arc_azure)
131+
132+
* **Aliyun OSS Storage** - [waffle_aliyun_oss](https://github.com/ug0/waffle_aliyun_oss)
133+
23134
## Attribution
24135

25136
Great thanks to Sean Stavropoulos (@stavro) for the original awesome work on the library.

‎lib/waffle.ex

+1-113
Original file line numberDiff line numberDiff line change
@@ -1,115 +1,3 @@
11
defmodule Waffle do
2-
@moduledoc ~S"""
3-
Waffle is a flexible file upload library for Elixir with straightforward integrations for Amazon S3 and ImageMagick.
4-
5-
## Installation
6-
7-
Add the latest stable release to your `mix.exs` file, along with the
8-
required dependencies for `ExAws` if appropriate:
9-
10-
defp deps do
11-
[
12-
{:waffle, "~> 1.1"},
13-
14-
# If using S3:
15-
{:ex_aws, "~> 2.1.2"},
16-
{:ex_aws_s3, "~> 2.0"},
17-
{:hackney, "~> 1.9"},
18-
{:sweet_xml, "~> 0.6"}
19-
]
20-
end
21-
22-
Then run `mix deps.get` in your shell to fetch the dependencies.
23-
24-
## Usage
25-
26-
After installing Waffle, another two things should be done:
27-
28-
1. setup a storage provider
29-
2. define a definition module
30-
31-
### Setup a storage provider
32-
33-
Waffle has two built-in storage providers:
34-
35-
* `Waffle.Storage.Local`
36-
* `Waffle.Storage.S3`
37-
38-
[Other available storage providers](#module-other-storage-providers)
39-
are supported by the community.
40-
41-
An example for setting up `Waffle.Storage.Local`:
42-
43-
config :waffle,
44-
storage: Waffle.Storage.Local,
45-
asset_host: "http://static.example.com" # or {:system, "ASSET_HOST"}
46-
47-
An example for setting up `Waffle.Storage.S3`:
48-
49-
config :waffle,
50-
storage: Waffle.Storage.S3,
51-
bucket: "custom_bucket", # or {:system, "AWS_S3_BUCKET"}
52-
asset_host: "http://static.example.com" # or {:system, "ASSET_HOST"}
53-
54-
config :ex_aws,
55-
json_codec: Jason
56-
# any configurations provided by https://github.com/ex-aws/ex_aws
57-
58-
### Define a definition module
59-
60-
Waffle requires a **definition module** which contains the relevant
61-
functions to store and retrieve files:
62-
63-
* Optional transformations of the uploaded file
64-
* Where to put your files (the storage directory)
65-
* How to name your files
66-
* How to secure your files (private? Or publicly accessible?)
67-
* Default placeholders
68-
69-
This module can be created manually or generated by `mix waffle.g`
70-
automatically.
71-
72-
As an example, we will generate a definition module for handling
73-
avatars:
74-
75-
mix waffle.g avatar
76-
77-
This should generate a file at `lib/[APP_NAME]_web/uploaders/avatar.ex`.
78-
Check this file for descriptions of configurable options.
79-
80-
## Examples
81-
82-
* [An example for Local storage driver](./local.html)
83-
* [An example for S3 storage driver](./s3.html)
84-
85-
## Usage with Ecto
86-
87-
Waffle comes with a companion package for use with Ecto. If you
88-
intend to use Waffle with Ecto, it is highly recommended you also
89-
add the
90-
[`waffle_ecto`](https://github.com/elixir-waffle/waffle_ecto)
91-
dependency. Benefits include:
92-
93-
* Changeset integration
94-
* Versioned urls for cache busting (`.../thumb.png?v=63601457477`)
95-
96-
## Other Storage Providers
97-
98-
* **Rackspace** - [arc_rackspace](https://github.com/lokalebasen/arc_rackspace)
99-
100-
* **Manta** - [arc_manta](https://github.com/onyxrev/arc_manta)
101-
102-
* **OVH** - [arc_ovh](https://github.com/stephenmoloney/arc_ovh)
103-
104-
* **Google Cloud Storage** - [waffle_gcs](https://github.com/kolorahl/waffle_gcs)
105-
106-
* **Microsoft Azure Storage** - [arc_azure](https://github.com/phil-a/arc_azure)
107-
108-
* **Aliyun OSS Storage** - [waffle_aliyun_oss](https://github.com/ug0/waffle_aliyun_oss)
109-
110-
## Further reading
111-
112-
* `Waffle.Definition`
113-
114-
"""
2+
@moduledoc File.read!("README.md")
1153
end

0 commit comments

Comments
 (0)