Misc doc changes

Besides other documentation changes, this commit ensures the generated HTML doc for HexDocs.pm will become the main reference doc for this Elixir library which leverage on latest features of ExDoc.
commanded · May 16, 2021 · 8b8aca5 · 8b8aca5
1 parent aa5a994
commit 8b8aca5
Show file tree

Hide file tree

Showing 8 changed files with 98 additions and 68 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,10 +1,31 @@
-/_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").
+commanded_ecto_projections-*.tar
+
+# Temporary files for e.g. tests.
+/tmp/
+
+# Misc.
 .DS_Store
 .elixir_ls
 /priv/plts/*.plt

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,17 +1,22 @@
 # Changelog
 
-## v1.2.1
+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).
+
+## v1.2.1 - 2020-12-03
 
 - Allow exceptions to be rescued by Commanded's event handler ([#37](https://github.com/commanded/commanded-ecto-projections/pull/37)).
 
-## v1.2.0
+## v1.2.0 - 2020-08-18
 
 - Support runtime projector names ([#32](https://github.com/commanded/commanded-ecto-projections/pull/32)).
 - Support `schema_prefix/2` function ([#33](https://github.com/commanded/commanded-ecto-projections/pull/33)).
 
 ---
 
-## v1.1.0
+## v1.1.0 - 2020-05-25
 
 ### Enhancements
 
@@ -20,7 +25,7 @@
 
 ---
 
-## v1.0.0
+## v1.0.0 - 2019-11-21
 
 ### Enhancements
 
@@ -30,7 +35,7 @@
 
 ---
 
-## v0.8.0
+## v0.8.0 - 2019-01-23
 
 ### Enhancements
 
@@ -57,21 +62,21 @@
 
 ---
 
-## v0.7.1
+## v0.7.1 - 2018-07-24
 
 ### Bug fixes
 
 - Ensure errors encountered while building the `Ecto.Multi` data structure within a `project` function are caught and passed to the `error/3` callback.
 
-## v0.7.0
+## v0.7.0 - 2018-07-22
 
 ### Enhancements
 
 - Support Commanded's event handler `error/3` callback ([#12](https://github.com/commanded/commanded-ecto-projections/pull/12)).
 
 ---
 
-## v0.6.0
+## v0.6.0 - 2017-09-29
 
 ### Enhancements
 
@@ -80,15 +85,15 @@
 
 ---
 
-## v0.5.0
+## v0.5.0 - 2017-09-15
 
 ### Enhancements
 
 - Allow an Ecto schema prefix to be defined in config or per handler ([#4](https://github.com/commanded/commanded-ecto-projections/pull/4)).
 
 ---
 
-## v0.4.0
+## v0.4.0 - 2017-08-03
 
 ### Enhancements
 

diff --git a/LICENSE → LICENSE.md b/LICENSE → LICENSE.md
@@ -1,4 +1,5 @@
 The MIT License (MIT)
+
 Copyright (c) 2017 Ben Smith ([email protected])
 
 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:

diff --git a/README.md b/README.md
@@ -1,36 +1,31 @@
-# Commanded Ecto projections
-
-Read model projections for [Commanded](https://github.com/commanded/commanded) CQRS/ES applications using [Ecto](https://github.com/elixir-ecto/ecto) for persistence.
-
----
-
-[Changelog](CHANGELOG.md)
-
-MIT License
+# Commanded Ecto Projections
 
 [![Build Status](https://travis-ci.com/commanded/commanded-ecto-projections.svg?branch=master)](https://travis-ci.com/commanded/commanded-ecto-projections)
-
----
+[![Module Version](https://img.shields.io/hexpm/v/commanded_ecto_projections.svg)](https://hex.pm/packages/commanded_ecto_projections)
+[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/commanded_ecto_projections/)
+[![Total Download](https://img.shields.io/hexpm/dt/commanded_ecto_projections.svg)](https://hex.pm/packages/commanded_ecto_projections)
+[![License](https://img.shields.io/hexpm/l/commanded_ecto_projections.svg)](https://github.com/commanded/commanded-ecto-projections/blob/master/LICENSE)
+[![Last Updated](https://img.shields.io/github/last-commit/commanded/commanded-ecto-projections.svg)](https://github.com/commanded/commanded-ecto-projections/commits/master)
 
 > This README and the following guides follow the `master` branch which may not be the currently published version.
->
-> [Read the documentation for the latest published version of Commanded Ecto projections on Hex](https://hexdocs.pm/commanded_ecto_projections/).
 
-### Overview
+Model projections for [Commanded](https://github.com/commanded/commanded) CQRS/ES applications using [Ecto](https://github.com/elixir-ecto/ecto) for persistence.
 
-- [Getting started](guides/Getting%20Started.md)
-- [Usage](guides/Usage.md)
-  - [Creating a read model](guides/Usage.md#creating-a-read-model)
-  - [Creating a projector](guides/Usage.md#creating-a-projector)
-  - [Supervision](guides/Usage.md#supervision)
-  - [Error handling](guides/Usage.md#error-handling)
-    - [`error/3` callback](guides/Usage.md#error3-callback)
-    - [Error handling example](guides/Usage.md#error-handling-example)
-  - [`after_update/3` callback](guides/Usage.md#after_update3-callback)
-  - [Schema prefix](guides/Usage.md#schema-prefix)
-  - [Rebuilding a projection](guides/Usage.md#rebuilding-a-projection)
+Read the [Changelog](CHANGELOG.md) for recent changes and the [Hex Docs](https://hexdocs.pm/commanded_ecto_projections/) on API usage.
 
----
+### Overview
+
+- [Getting started](guides/getting_started.md)
+- [Usage](guides/usage.md)
+  - [Creating a read model](guides/usage.md#creating-a-read-model)
+  - [Creating a projector](guides/usage.md#creating-a-projector)
+  - [Supervision](guides/usage.md#supervision)
+  - [Error handling](guides/usage.md#error-handling)
+    - [`error/3` callback](guides/usage.md#error3-callback)
+    - [Error handling example](guides/usage.md#error-handling-example)
+  - [`after_update/3` callback](guides/usage.md#after_update3-callback)
+  - [Schema prefix](guides/usage.md#schema-prefix)
+  - [Rebuilding a projection](guides/usage.md#rebuilding-a-projection)
 
 ### Example projector
 
@@ -77,3 +72,10 @@ mix test
 Please [open an issue](https://github.com/commanded/commanded-ecto-projections/issues) if you encounter a problem, or need assistance. You can also seek help in the [Gitter chat room](https://gitter.im/commanded/Lobby) for Commanded.
 
 For commercial support, and consultancy, please contact [Ben Smith](mailto:[email protected]).
+
+## Copyright and License
+
+Copyright (c) 2017 Ben Smith
+
+This library is released under the MIT License. See the [LICENSE.md](./LICENSE.md) file
+for further details.
diff --git a/guides/Getting Started.md → guides/getting_started.md b/guides/Getting Started.md → guides/getting_started.md
@@ -2,21 +2,24 @@
 
 You should already have [Ecto](https://github.com/elixir-ecto/ecto) installed and configured before proceeding. Please follow Ecto's [Getting Started](https://hexdocs.pm/ecto/getting-started.html) guide to get going first.
 
-1. Add `commanded_ecto_projections` to your list of dependencies in `mix.exs`:
+1.  Add `:commanded_ecto_projections` to your list of dependencies in `mix.exs`:
 
     ```elixir
     def deps do
-      [{:commanded_ecto_projections, "~> 1.2"}]
+      [
+        {:commanded_ecto_projections, "~> 1.2"}
+      ]
     end
     ```
 
-2. Generate an Ecto migration in your app:
+2.  Generate an Ecto migration in your app:
 
     ```console
     $ mix ecto.gen.migration create_projection_versions
     ```
 
-3. Modify the generated migration, in `priv/repo/migrations`, to create the `projection_versions` table:
+3.  Modify the generated migration, in `priv/repo/migrations`, to create the
+    `projection_versions` table:
 
     ```elixir
     defmodule CreateProjectionVersions do
@@ -33,13 +36,13 @@ You should already have [Ecto](https://github.com/elixir-ecto/ecto) installed an
     end
     ```
 
-5. Run the Ecto migration:
+5.  Run the Ecto migration:
 
     ```console
     $ mix ecto.migrate
     ```
 
-6. Define your first read model projector:
+6.  Define your first read model projector:
 
     ```elixir
     defmodule MyApp.ExampleProjector do
@@ -50,4 +53,5 @@ You should already have [Ecto](https://github.com/elixir-ecto/ecto) installed an
     end
     ```
 
-Refer to the Usage guide for more detail on how to configure and use a read model projector.
+Refer to the [Usage guide](./guides/usage.md) for more detail on how to
+configure and use a read model projector.
diff --git a/guides/Usage.md → guides/usage.md b/guides/Usage.md → guides/usage.md
diff --git a/lib/projections/ecto.ex b/lib/projections/ecto.ex
@@ -125,7 +125,7 @@ defmodule Commanded.Projections.Ecto do
   `Ecto.Multi` struct that were executed within the database transaction.
 
   You could use this function to notify subscribers that the read model has been
-  updated, such as by publishling changes via Phoenix PubSub channels.
+  updated, such as by publishing changes via Phoenix PubSub channels.
 
   ## Example
 

diff --git a/mix.exs b/mix.exs
@@ -1,6 +1,7 @@
 defmodule Commanded.Projections.Ecto.Mixfile do
   use Mix.Project
 
+  @source_url "https://github.com/commanded/commanded-ecto-projections"
   @version "1.2.1"
 
   def project do
@@ -10,13 +11,12 @@ defmodule Commanded.Projections.Ecto.Mixfile do
       elixir: "~> 1.6",
       elixirc_paths: elixirc_paths(Mix.env()),
       aliases: aliases(),
-      description: description(),
       package: package(),
       build_embedded: Mix.env() == :prod,
       start_permanent: Mix.env() == :prod,
       deps: deps(),
-      dialyzer: dialyzer(),
-      docs: docs()
+      docs: docs(),
+      dialyzer: dialyzer()
     ]
   end
 
@@ -41,7 +41,7 @@ defmodule Commanded.Projections.Ecto.Mixfile do
 
       # Test & build tooling
       {:dialyxir, "~> 1.0.0", only: [:dev, :test], runtime: false},
-      {:ex_doc, ">= 0.0.0", only: :dev},
+      {:ex_doc, ">= 0.0.0", only: :dev, runtime: false},
       {:mix_test_watch, "~> 1.0", only: :dev, runtime: false}
     ]
   end
@@ -53,12 +53,6 @@ defmodule Commanded.Projections.Ecto.Mixfile do
     ]
   end
 
-  defp description do
-    """
-    Read model projections for Commanded using Ecto.
-    """
-  end
-
   defp dialyzer do
     [
       plt_add_apps: [:ecto, :ex_unit],
@@ -69,21 +63,22 @@ defmodule Commanded.Projections.Ecto.Mixfile do
 
   defp docs do
     [
-      main: "Commanded.Projections.Ecto",
-      canonical: "http://hexdocs.pm/commanded_ecto_projections",
-      source_ref: "v#{@version}",
       extra_section: "GUIDES",
       extras: [
         "CHANGELOG.md",
-        "guides/Getting Started.md",
-        "guides/Usage.md"
+        {:"LICENSE.md", [title: "License"]},
+        {:"README.md", [title: "Overview"]},
+        "guides/getting_started.md",
+        "guides/usage.md"
       ],
       groups_for_extras: [
-        Introduction: [
-          "guides/Getting Started.md",
-          "guides/Usage.md"
-        ]
-      ]
+        Introduction: Path.wildcard("guides/*.md")
+      ],
+      main: "readme",
+      canonical: "http://hexdocs.pm/commanded_ecto_projections",
+      source_url: @source_url,
+      source_ref: "v#{@version}",
+      formatters: ["html"]
     ]
   end
 
@@ -95,8 +90,10 @@ defmodule Commanded.Projections.Ecto.Mixfile do
         ".formatter.exs",
         "README*",
         "LICENSE*",
+        "CHANGELOG*",
         "priv/repo/migrations"
       ],
+      description: "Read model projections for Commanded using Ecto.",
       maintainers: ["Ben Smith"],
       licenses: ["MIT"],
       links: %{