Update docs + usage guide

Author: mcrumm

README.md

@@ -1,75 +1,60 @@
-Briefly
-=======
+# Briefly
+
+<!-- MDOC -->
 
 ![Build Status](https://github.com/CargoSense/briefly/actions/workflows/main.yml/badge.svg)
 
 Simple, robust temporary file support for Elixir.
 
 ## Highlighted Features
 
-* Create temporary files with prefix and extname options
-* Files are removed after the process that requested the file dies
-* File creation is based on [Plug.Upload](http://hexdocs.pm/plug/Plug.Upload.html)'s robust retry logic
-* Configurable; built-in support for system environment variables and fallbacks
+* Create temporary files with prefix and extname options.
+* Files are removed after the requesting process exits.
+* File creation is based on [Plug.Upload](http://hexdocs.pm/plug/Plug.Upload.html)'s robust retry logic.
+* Configurable; built-in support for system environment variables and fallbacks.
 
-## Installation
+## Usage
 
-Add as a dependency to your `mix.exs`:
+The fastest way to use Briefly is with [`Mix.install/2`](https://hexdocs.pm/mix/Mix.html#install/2) (requires Elixir v1.12+):
 
 ```elixir
-def deps do
-  [
-    briefly: "~> 0.3"
-  ]
-end
-```
+Mix.install([
+  {:briefly, "~> 0.4.0"}
+])
 
-or grab the latest with:
+{:ok, path} = Briefly.create()
+File.write!(path, "My temp file contents")
+File.read!(path)
+# => "My temp file contents"
 
-```elixir
-{
-  :briefly,
-  git: "https://github.com/CargoSense/briefly",
-  ref: "2526e9674a4e6996137e066a1295ea60962712b8"
-  # "~> 0.4" https://github.com/CargoSense/briefly/issues/17
-}
+# When this process exits, the file at `path` is removed
 ```
 
-Install it with `mix deps.get`.
+If you want to use Briefly in a Mix project, you can add the above dependency to your list of dependencies in `mix.exs`.
 
-## Example
+Briefly can also create a temporary directory:
 
-Create a file:
 
 ```elixir
-{:ok, path} = Briefly.create
-File.write!(path, "Some Text")
-content = File.read!(path)
-# When this process exits, the file at `path` is removed
-```
-
-Create a directory:
-
-```elixir
-{:ok, path} = Briefly.create(directory: true)
-File.write!(Path.join(path, "test.txt"), "Some Text")
+{:ok, dir} = Briefly.create(directory: true)
+File.write!(Path.join(dir, "test.txt"), "Some Text")
 # When this process exits, the directory and file are removed
 ```
 
-See [the documentation](http://hexdocs.pm/briefly/Briefly.html#create/1) to see
-the options that available to `Briefly.create/1` and `Briefly.create!/1`.
+Refer to [the documentation](http://hexdocs.pm/briefly/Briefly.html#create/1) for a list of options that are available to `Briefly.create/1` and `Briefly.create!/1`.
 
 ## Configuration
 
 The default, out-of-the-box settings for Briefly are equivalent to the
 following Mix config:
 
 ```elixir
+# config/config.exs
 config :briefly,
   directory: [{:system, "TMPDIR"}, {:system, "TMP"}, {:system, "TEMP"}, "/tmp"],
   default_prefix: "briefly",
   default_extname: ""
-  ```
+```
 
 `directory` here declares an ordered list of possible directory definitions that Briefly will check in order.
 
@@ -79,6 +64,8 @@ You can override the settings with your own candidates in your application Mix
 config (and pass `prefix` and `extname` to `Briefly.create` to override
 `default_prefix` and `default_extname` on a case-by-case basis).
 
+<!-- MDOC -->
+
 ## License
 
-See [LICENSE](./LICENSE).
+Briefly source code is released under Apache License 2.0. Refer to the [LICENSE](./LICENSE) file for more information.

guides/usage.livemd

@@ -0,0 +1,55 @@
+# Briefly Usage Guide
+
+```elixir
+Mix.install([
+  {:briefly, "~> 0.4.0"}
+])
+```
+
+## Temporary Files
+
+Use Briefly to create a temporary file:
+
+```elixir
+{:ok, path} = Briefly.create()
+```
+
+Then you can write to the path and read the contents of the file:
+
+```elixir
+File.write!(path, "My temp file contents")
+File.read!(path)
+```
+
+When this process exits, the file at `path` is removed.
+
+## Temporary Directories
+
+Briefly can also create a temporary directory:
+
+```elixir
+{:ok, dir} = Briefly.create(directory: true)
+```
+
+You can use [`File.stat/1`](https://hexdocs.pm/elixir/File.html#stat/1) to check the type:
+
+```elixir
+File.stat!(dir).type
+```
+
+Write to a file in the directory:
+
+```elixir
+dir |> Path.join("test.txt") |> File.write!("Some Text")
+dir |> Path.join("test.txt") |> File.read!()
+```
+
+When this process exits, the directory at `dir` and the files within are removed.
+
+## Cleanup
+
+You can always cleanup any temporary paths already created:
+
+```elixir
+Briefly.cleanup()
+```

lib/briefly.ex

@@ -1,5 +1,9 @@
 defmodule Briefly do
-  @moduledoc File.read!("#{__DIR__}/../README.md")
+  @external_resource "README.md"
+  @moduledoc @external_resource
+             |> File.read!()
+             |> String.split("<!-- MDOC -->")
+             |> Enum.fetch!(1)
 
   use Application
 

mix.exs

@@ -1,16 +1,25 @@
 defmodule Briefly.Mixfile do
   use Mix.Project
 
+  @version "0.4.0"
+
+  @source_url "https://github.com/CargoSense/briefly"
+
   def project do
     [
       app: :briefly,
       version: "0.4.0",
       elixir: "~> 1.11",
-      source_url: "https://github.com/CargoSense/briefly",
+      source_url: @source_url,
       build_embedded: Mix.env() == :prod,
       start_permanent: Mix.env() == :prod,
       package: package(),
-      deps: deps()
+      deps: deps(),
+      docs: docs(),
+      preferred_cli_env: [
+        {:docs, :docs},
+        {:"hex.publish", :docs}
+      ]
     ]
   end
 
@@ -32,17 +41,29 @@ defmodule Briefly.Mixfile do
   # Type `mix help deps` for more examples and options
   defp deps do
     [
-      {:ex_doc, "~> 0.19", only: :dev, runtime: false}
+      {:ex_doc, "~> 0.29", only: :docs, runtime: false}
     ]
   end
 
   defp package do
     [
       description: "Simple, robust temporary file support",
       files: ["lib", "config", "mix.exs", "README*", "LICENSE"],
-      contributors: ["Bruce Williams"],
-      licenses: ["Apache 2"],
-      links: %{github: "https://github.com/CargoSense/briefly"}
+      contributors: ["Bruce Williams", "Michael A. Crumm Jr."],
+      licenses: ["Apache-2.0"],
+      links: %{"GitHub" => @source_url}
+    ]
+  end
+
+  defp docs do
+    [
+      source_url: @source_url,
+      source_ref: "v#{@version}",
+      deps: [],
+      language: "en",
+      formatters: ["html"],
+      main: "usage",
+      extras: ["guides/usage.livemd"]
     ]
   end
 

mix.lock

@@ -1,8 +1,8 @@
 %{
-  "earmark_parser": {:hex, :earmark_parser, "1.4.13", "0c98163e7d04a15feb62000e1a891489feb29f3d10cb57d4f845c405852bbef8", [:mix], [], "hexpm", "d602c26af3a0af43d2f2645613f65841657ad6efc9f0e361c3b6c06b578214ba"},
-  "ex_doc": {:hex, :ex_doc, "0.24.2", "e4c26603830c1a2286dae45f4412a4d1980e1e89dc779fcd0181ed1d5a05c8d9", [: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", "e134e1d9e821b8d9e4244687fb2ace58d479b67b282de5158333b0d57c6fb7da"},
-  "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"},
+  "earmark_parser": {:hex, :earmark_parser, "1.4.29", "149d50dcb3a93d9f3d6f3ecf18c918fb5a2d3c001b5d3305c926cddfbd33355b", [:mix], [], "hexpm", "4902af1b3eb139016aed210888748db8070b8125c2342ce3dcae4f38dcc63503"},
+  "ex_doc": {:hex, :ex_doc, "0.29.1", "b1c652fa5f92ee9cf15c75271168027f92039b3877094290a75abcaac82a9f77", [:mix], [{:earmark_parser, "~> 1.4.19", [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", "b7745fa6374a36daf484e2a2012274950e084815b936b1319aeebcf7809574f6"},
+  "makeup": {:hex, :makeup, "1.1.0", "6b67c8bc2882a6b6a445859952a602afc1a41c2e08379ca057c0f525366fc3ca", [:mix], [{:nimble_parsec, "~> 1.2.2 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "0a45ed501f4a8897f580eabf99a2e5234ea3e75a4373c8a52824f6e873be57a6"},
+  "makeup_elixir": {:hex, :makeup_elixir, "0.16.0", "f8c570a0d33f8039513fbccaf7108c5d750f47d8defd44088371191b76492b0b", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.2.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "28b2cbdc13960a46ae9a8858c4bebdec3c9a6d7b4b9e7f4ed1502f8159f338e7"},
   "makeup_erlang": {:hex, :makeup_erlang, "0.1.1", "3fcb7f09eb9d98dc4d208f49cc955a34218fc41ff6b84df7c75b3e6e533cc65f", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "174d0809e98a4ef0b3309256cbf97101c6ec01c4ab0b23e926a9e17df2077cbb"},
-  "nimble_parsec": {:hex, :nimble_parsec, "1.1.0", "3a6fca1550363552e54c216debb6a9e95bd8d32348938e13de5eda962c0d7f89", [:mix], [], "hexpm", "08eb32d66b706e913ff748f11694b17981c0b04a33ef470e33e11b3d3ac8f54b"},
+  "nimble_parsec": {:hex, :nimble_parsec, "1.2.3", "244836e6e3f1200c7f30cb56733fd808744eca61fd182f731eac4af635cc6d0b", [:mix], [], "hexpm", "c8d789e39b9131acf7b99291e93dae60ab48ef14a7ee9d58c6964f59efb570b0"},
 }