Misc doc changes

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.
revelrylabs · Jun 6, 2021 · 5f0a678 · 5f0a678
1 parent 327d3c9
commit 5f0a678
Show file tree

Hide file tree

Showing 13 changed files with 144 additions and 86 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,19 +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
 
-/.elixir_ls
+# Ignore package tarball (built via "mix hex.build").
+ecto-soft-delete-*.tar
+
+# Temporary files, for example, from tests.
+/tmp/
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -11,7 +11,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## [2.0.1] - 2020-05-08
 
-- Add logic to `Ecto.SoftDelete.Repo.prepare_query` to respect `where` clauses that explicitly include records where deleted_at is not nil 
+- Add logic to `Ecto.SoftDelete.Repo.prepare_query` to respect `where` clauses
+  that explicitly include records where deleted_at is not nil
 
 ## [2.0.0] - 2020-05-06
 
@@ -22,16 +23,20 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ### Added
 
-- `Ecto.SoftDelete.Repo` for adding soft delete functions to repositories.
+- `Ecto.SoftDelete.Repo` for adding soft delete functions to repositories
 
 ## [1.0.0] - 2019-02-15
 
 ### Added
 
 - Ecto 3 support
 
-## [0.2.0]
+## [0.2.0] - 2018-12-31
 
 ### Fixed
 
 - Missing license (MIT)
+
+## [0.1.0] - 2017-12-20
+
+- Initial release
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,11 +1,13 @@
-# Setup for Development
+# Contributing
 
-```
+## Setup for Development
+
+```bash
 git clone https://github.com/revelrylabs/ecto_soft_delete
 mix deps.get
 ```
 
-# Submitting Changes
+## Submitting Changes
 
 1. Fork the repository.
 2. Set up the package per the instructions above and ensure `mix test`

diff --git a/LICENSE b/LICENSE
diff --git a/LICENSE.md b/LICENSE.md
@@ -0,0 +1,19 @@
+Copyright 2018 Revelry Labs LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
diff --git a/README.md b/README.md
@@ -1,19 +1,43 @@
+# EctoSoftDelete
+
 [![Build Status](https://travis-ci.org/revelrylabs/ecto_soft_delete.svg?branch=master)](https://travis-ci.org/revelrylabs/ecto_soft_delete)
-[![Hex.pm](https://img.shields.io/hexpm/dt/ecto_soft_delete.svg)](https://hex.pm/packages/ecto_soft_delete)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Coverage Status](https://opencov.prod.revelry.net/projects/21/badge.svg)](https://opencov.prod.revelry.net/projects/21)
-
-# EctoSoftDelete
+[![Module Version](https://img.shields.io/hexpm/v/ecto_soft_delete.svg)](https://hex.pm/packages/ecto_soft_delete)
+[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/ecto_soft_delete/)
+[![Total Download](https://img.shields.io/hexpm/dt/ecto_soft_delete.svg)](https://hex.pm/packages/ecto_soft_delete)
+[![License](https://img.shields.io/hexpm/l/ecto_soft_delete.svg)](https://github.com/revelrylabs/ecto_soft_delete/blob/master/LICENSE)
+[![Last Updated](https://img.shields.io/github/last-commit/revelrylabs/ecto_soft_delete.svg)](https://github.com/revelrylabs/ecto_soft_delete/commits/master)
 
 Adds columns, fields, and queries for soft deletion with Ecto.
 
-[Documentation](https://hexdocs.pm/ecto_soft_delete)
+## Installation
+
+The package can be installed by adding `:ecto_soft_delete` to your list of
+dependencies in `mix.exs`:
+
+Add to mix.exs:
+
+```elixir
+defp deps do
+  [
+    {:ecto_soft_delete, "~> 1.0"}
+  ]
+end
+```
+
+and do:
+
+```
+mix deps.get
+```
 
 ## Usage
 
 ### Migrations
 
-In migrations for schemas to support soft deletion, import `Ecto.SoftDelete.Migration`. Next, add `soft_delete_columns()` when creating a table
+In migrations for schemas to support soft deletion, import
+`Ecto.SoftDelete.Migration`. Next, add `soft_delete_columns()` when creating a
+table:
 
 ```elixir
 defmodule MyApp.Repo.Migrations.CreateUser do
@@ -33,23 +57,26 @@ end
 
 ### Schemas
 
-Import `Ecto.SoftDelete.Schema` into your Schema module, then add `soft_delete_schema()` to your schema
+Import `Ecto.SoftDelete.Schema` into your Schema module, then add
+`soft_delete_schema()` to your schema:
 
 ```elixir
-  defmodule User do
-    use Ecto.Schema
-    import Ecto.SoftDelete.Schema
+defmodule User do
+  use Ecto.Schema
+  import Ecto.SoftDelete.Schema
 
-    schema "users" do
-      field :email,           :string
-      soft_delete_schema()
-    end
+  schema "users" do
+    field :email,           :string
+    soft_delete_schema()
   end
+end
 ```
 
 ### Queries
 
-To query for items that have not been deleted, use `with_undeleted(query)` which will filter out deleted items using the `deleted_at` column produced by the previous 2 steps
+To query for items that have not been deleted, use `with_undeleted(query)`
+which will filter out deleted items using the `deleted_at` column produced by
+the previous 2 steps:
 
 ```elixir
 import Ecto.SoftDelete.Query
@@ -60,10 +87,12 @@ query = from(u in User, select: u)
 results = Repo.all(query)
 ```
 
-## Repos
+### Repos
 
 To support deletion in repos, just add `use Ecto.SoftDelete.Repo` to your repo.
-After that, the functions `soft_delete!/1`, `soft_delete/1` and `soft_delete_all/1` will be available for you.
+
+After that, the functions `soft_delete!/1`, `soft_delete/1` and
+`soft_delete_all/1` will be available for you.
 
 ```elixir
 # repo.ex
@@ -88,31 +117,18 @@ post = Repo.get!(Post, 42)
 struct = Repo.soft_delete!(post)
 ```
 
-## Installation
-
-Add to mix.exs:
-
-```elixir
-defp deps do
-  [{:ecto_soft_delete, "~> 1.0"}]
-end
-```
-
-and do
-
-```
-mix deps.get
-```
-
-## Configuration
+## Contributing
 
-There are currently no configuration options.
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/revelrylabs/ecto_soft_delete. Check out
+[CONTRIBUTING.md](./CONTRIBUTING.md) for more info.
 
-## Usage
+Everyone is welcome to participate in the project. We expect contributors to
+adhere the Contributor Covenant Code of Conduct (see [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md)).
 
-## Contributing
+## Copyright and License
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/revelrylabs/ecto_soft_delete. Check out [CONTRIBUTING.md](https://github.com/revelrylabs/ecto_soft_delete/blob/master/CONTRIBUTING.md) for more info.
+Copyright (c) 2018 Revelry Labs LLC
 
-Everyone is welcome to participate in the project. We expect contributors to
-adhere the Contributor Covenant Code of Conduct (see [CODE_OF_CONDUCT.md](https://github.com/revelrylabs/ecto_soft_delete/blob/master/CODE_OF_CONDUCT.md)).
+This library is released under the MIT License. See the [LICENSE.md](./LICENSE.md) file
+for further details.
diff --git a/lib/ecto/soft_delete_migration.ex b/lib/ecto/soft_delete_migration.ex
@@ -1,12 +1,14 @@
 defmodule Ecto.SoftDelete.Migration do
   @moduledoc """
-  Contains functions to add soft delete columns to a table during migrations
+  Contains functions to add soft delete columns to a table during migrations.
   """
 
   use Ecto.Migration
 
   @doc """
-  Adds deleted_at column to a table. This column is used to track if an item is deleted or not and when
+  Adds deleted_at column to a table.
+
+  This column is used to track if an item is deleted or not and when:
 
       defmodule MyApp.Repo.Migrations.CreateUser do
         use Ecto.Migration

diff --git a/lib/ecto/soft_delete_query.ex b/lib/ecto/soft_delete_query.ex
@@ -1,12 +1,12 @@
 defmodule Ecto.SoftDelete.Query do
   @moduledoc """
-  functions for querying data that is (or is not) soft deleted
+  Functions for querying data that is (or is not) soft deleted.
   """
 
   import Ecto.Query
 
   @doc """
-  Returns a query that searches only for undeleted items
+  Returns a query that searches only for undeleted items.
 
       query = from(u in User, select: u)
       |> with_undeleted

diff --git a/lib/ecto/soft_delete_repo.ex b/lib/ecto/soft_delete_repo.ex
@@ -28,7 +28,9 @@ defmodule Ecto.SoftDelete.Repo do
 
   @doc """
   Soft deletes a struct.
+
   Updates the `deleted_at` field with the current datetime in UTC.
+
   It returns `{:ok, struct}` if the struct has been successfully
   soft deleted or `{:error, changeset}` if there was a validation
   or a known constraint error.

diff --git a/lib/ecto/soft_delete_schema.ex b/lib/ecto/soft_delete_schema.ex
@@ -1,10 +1,10 @@
 defmodule Ecto.SoftDelete.Schema do
   @moduledoc """
-  Contains schema macros to add soft delete fields to a schema
+  Contains schema macros to add soft delete fields to a schema.
   """
 
   @doc """
-  Adds the deleted_at column to a schema
+  Adds the `deleted_at` column to a schema.
 
       defmodule User do
         use Ecto.Schema

diff --git a/mix.exs b/mix.exs
@@ -1,10 +1,13 @@
 defmodule EctoSoftDelete.Mixfile do
   use Mix.Project
 
+  @source_url "https://github.com/revelrylabs/ecto_soft_delete"
+  @version "2.0.2"
+
   def project do
     [
       app: :ecto_soft_delete,
-      version: "2.0.2",
+      version: @version,
       elixir: "~> 1.9",
       elixirc_paths: elixirc_paths(Mix.env()),
       build_embedded: Mix.env() == :prod,
@@ -17,8 +20,8 @@ defmodule EctoSoftDelete.Mixfile do
         "coveralls.html": :test
       ],
       deps: deps(),
+      docs: docs(),
       package: package(),
-      description: description()
     ]
   end
 
@@ -33,20 +36,15 @@ defmodule EctoSoftDelete.Mixfile do
     [
       {:ecto_sql, "~> 3.0"},
       {:postgrex, ">= 0.0.0", only: [:test]},
-      {:ex_doc, "~> 0.16", only: [:dev, :test]},
+      {:ex_doc, ">= 0.0.0", only: [:dev, :test]},
       {:credo, "~> 1.0", only: [:dev, :test]},
       {:excoveralls, "~> 0.8", only: [:dev, :test]}
     ]
   end
 
-  defp description do
-    """
-    Soft deletion with Ecto.
-    """
-  end
-
   defp package do
     [
+      description: "Soft deletion with Ecto.",
       files: ["lib", "mix.exs", "README.md", "LICENSE", "CHANGELOG.md"],
       maintainers: ["Bryan Joseph", "Luke Ledet"],
       licenses: ["MIT"],
@@ -56,4 +54,20 @@ defmodule EctoSoftDelete.Mixfile do
       build_tools: ["mix"]
     ]
   end
+
+  defp docs do
+    [
+      extras: [
+        "CHANGELOG.md": [title: "Changelog"],
+        "CONTRIBUTING.md": [title: "Contributing"],
+        "CODE_OF_CONDUCT.md": [title: "Code of Conduct"],
+        "LICENSE.md": [title: "License"],
+        "README.md": [title: "Overview"]
+      ],
+      main: "readme",
+      source_url: @source_url,
+      source_ref: "v#{@version}",
+      formatters: ["html"]
+    ]
+  end
 end