From e3fad2aa6f0c79a7bc52f8821d36e28357245878 Mon Sep 17 00:00:00 2001 From: Kian-Meng Ang Date: Wed, 3 Mar 2021 21:34:41 +0800 Subject: [PATCH] Misc doc changes Besides other changes, this commit ensures the generated HTML doc for HexDocs.pm will become the main source doc for this Elixir library which leverage on ExDoc features. List of changes: * Use common source url * Update gitignore * Set readme as main html page * Fix markdowns * Add changelog to html page * Add changelog link to hex info page * Badges and more badges! * Use and set latest ex_doc --- .gitignore | 29 +++++++++++++++++--- README.md | 79 ++++++++++++++++++++++++++++++------------------------ mix.exs | 25 +++++++++++------ mix.lock | 9 ++++--- 4 files changed, 91 insertions(+), 51 deletions(-) diff --git a/.gitignore b/.gitignore index 86e4c3f..092a98b 100644 --- a/.gitignore +++ b/.gitignore @@ -1,9 +1,30 @@ -/_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"). +assertions-*.tar + +# Temporary files for e.g. tests. +/tmp/ + +# Misc. *.beam /config/*.secret.exs diff --git a/README.md b/README.md index cc17f59..6ff1652 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,21 @@ -# Assertions [![Hex Version](https://img.shields.io/hexpm/v/assertions.svg)](https://hex.pm/packages/assertions) [![Build Status](https://travis-ci.org/devonestes/assertions.svg?branch=master)](https://travis-ci.org/devonestes/assertions) +# Assertions + +[![Build Status](https://travis-ci.org/devonestes/assertions.svg?branch=master)](https://travis-ci.org/devonestes/assertions) +[![Module Version](https://img.shields.io/hexpm/v/assertions.svg)](https://hex.pm/packages/assertions) +[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/assertions/) +[![Total Download](https://img.shields.io/hexpm/dt/assertions.svg)](https://hex.pm/packages/assertions) +[![License](https://img.shields.io/hexpm/l/assertions.svg)](https://github.com/devonestes/assertions/blob/master/LICENSE) +[![Last Updated](https://img.shields.io/github/last-commit/devonestes/assertions.svg)](https://github.com/devonestes/assertions/commits/master) ## Installation -Add `assertions` to your list of dependencies in `mix.exs`: +Add `:assertions` to your list of dependencies in `mix.exs`: ```elixir def deps do - [{:assertions, "~> 0.10", only: :test}] + [ + {:assertions, "~> 0.10", only: :test} + ] end ``` @@ -92,7 +101,7 @@ defmodule UsersTest do alice = Factory.insert(:user, name: "Alice") bob = Factory.insert(:user, name: "Bob") - updated_names = + updated_names = [{alice, %{name: "Alice A."}, {bob, %{name: "Bob B."}}}] |> Users.update_all() |> Enum.map(& &1.name) @@ -190,22 +199,22 @@ end The output you get from that failure looks like this: -``` - Expected truthy, got false - code: assert Enum.any?(list, fn map_in_list -> Map.get(map_in_list, :key) == map.key() end) - arguments: +```elixir +Expected truthy, got false +code: assert Enum.any?(list, fn map_in_list -> Map.get(map_in_list, :key) == map.key() end) +arguments: - # 1 - [ - %{big: :map, of: :keys, with: :lots}, - %{another: :big, key: :values, store: :with} - ] + # 1 + [ + %{big: :map, of: :keys, with: :lots}, + %{another: :big, key: :values, store: :with} + ] - # 2 - #Function<21.25555998/1 in Assertions.FailureExamples."test example"/1> + # 2 + #Function<21.25555998/1 in Assertions.FailureExamples."test example"/1> - stacktrace: - test/failure_examples.exs:207: (test) +stacktrace: + test/failure_examples.exs:207: (test) ``` That's not really helpful. What we wanted to know was essentially "is a map with @@ -227,24 +236,24 @@ end And then the output looks like this: -``` - Map matching the values for keys `:key` not found - code: assert_map_in_list(map, list, [:key]) - arguments: - - # 1 - %{key: :value, really: :helpful, stores: :are} - - # 2 - [ - %{big: :map, of: :keys, with: :lots}, - %{another: :big, key: :values, store: :with} - ] - - left: %{key: :value} - right: [%{}, %{key: :values}] - stacktrace: - test/failure_examples.exs:206: (test) +```elixir +Map matching the values for keys `:key` not found +code: assert_map_in_list(map, list, [:key]) +arguments: + + # 1 + %{key: :value, really: :helpful, stores: :are} + + # 2 + [ + %{big: :map, of: :keys, with: :lots}, + %{another: :big, key: :values, store: :with} + ] + +left: %{key: :value} +right: [%{}, %{key: :values}] +stacktrace: + test/failure_examples.exs:206: (test) ``` The error message there in the `left` and `right` keys shrinks down the output diff --git a/mix.exs b/mix.exs index 62a49f8..55e8ce3 100644 --- a/mix.exs +++ b/mix.exs @@ -1,6 +1,8 @@ defmodule Assertions.MixProject do use Mix.Project + @source_url "https://github.com/devonestes/assertions" + def project do [ app: :assertions, @@ -10,11 +12,7 @@ defmodule Assertions.MixProject do description: description(), package: package(), name: "Assertions", - source_url: "https://github.com/devonestes/assertions", - docs: [ - main: "Assertions", - extras: ["README.md"] - ] + docs: docs() ] end @@ -29,17 +27,28 @@ defmodule Assertions.MixProject do defp package do [ - files: ~w(lib mix.exs README.md LICENSE .formatter.exs), + files: ~w(lib mix.exs CHANGELOG.md README.md LICENSE .formatter.exs), licenses: ["MIT"], - links: %{"GitHub" => "https://github.com/devonestes/assertions"} + links: %{ + "Changelog" => "https://hexdocs.pm/assertions/changelog.html", + "GitHub" => @source_url + } ] end defp deps() do [ - {:ex_doc, "~> 0.19", only: [:dev, :test], runtime: false}, + {:ex_doc, ">= 0.0.0", only: [:dev, :test], runtime: false}, {:ecto, "~> 3.3", only: [:dev, :test], runtime: false}, {:absinthe, "~> 1.5.0-rc.5", only: [:dev, :test], runtime: false} ] end + + defp docs do + [ + extras: ["CHANGELOG.md", "README.md"], + main: "readme", + source_url: @source_url + ] + end end diff --git a/mix.lock b/mix.lock index 822f8f4..aa7002b 100644 --- a/mix.lock +++ b/mix.lock @@ -2,13 +2,14 @@ "absinthe": {:hex, :absinthe, "1.5.0-rc.5", "90b6335d452bfe72532257bb60c54793f6b8c4992b35b6861dc9adea5d01f463", [:mix], [{:dataloader, "~> 1.0.0", [hex: :dataloader, repo: "hexpm", optional: true]}, {:decimal, "~> 1.0", [hex: :decimal, repo: "hexpm", optional: true]}, {:nimble_parsec, "~> 0.5", [hex: :nimble_parsec, repo: "hexpm", optional: false]}, {:telemetry, "~> 0.4.0", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm", "7caf5b2d7d4be5a401dc4a17d219d44650af5dce4fe635687ca543c1823047a6"}, "decimal": {:hex, :decimal, "1.8.1", "a4ef3f5f3428bdbc0d35374029ffcf4ede8533536fa79896dd450168d9acdf3c", [:mix], [], "hexpm", "3cb154b00225ac687f6cbd4acc4b7960027c757a5152b369923ead9ddbca7aec"}, "earmark": {:hex, :earmark, "1.3.1", "73812f447f7a42358d3ba79283cfa3075a7580a3a2ed457616d6517ac3738cb9", [:mix], [], "hexpm", "000aaeff08919e95e7aea13e4af7b2b9734577b3e6a7c50ee31ee88cab6ec4fb"}, + "earmark_parser": {:hex, :earmark_parser, "1.4.12", "b245e875ec0a311a342320da0551da407d9d2b65d98f7a9597ae078615af3449", [:mix], [], "hexpm", "711e2cc4d64abb7d566d43f54b78f7dc129308a63bc103fbd88550d2174b3160"}, "ecto": {:hex, :ecto, "3.3.1", "82ab74298065bf0c64ca299f6c6785e68ea5d6b980883ee80b044499df35aba1", [:mix], [{:decimal, "~> 1.6", [hex: :decimal, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: true]}], "hexpm", "e6c614dfe3bcff2d575ce16d815dbd43f4ee1844599a83de1eea81976a31c174"}, - "ex_doc": {:hex, :ex_doc, "0.19.2", "6f4081ccd9ed081b6dc0bd5af97a41e87f5554de469e7d76025fba535180565f", [:mix], [{:earmark, "~> 1.2", [hex: :earmark, repo: "hexpm", optional: false]}, {:makeup_elixir, "~> 0.10", [hex: :makeup_elixir, repo: "hexpm", optional: false]}], "hexpm", "4eae888633d2937e0a8839ae6002536d459c22976743c9dc98dd05941a06c016"}, + "ex_doc": {:hex, :ex_doc, "0.23.0", "a069bc9b0bf8efe323ecde8c0d62afc13d308b1fa3d228b65bca5cf8703a529d", [:mix], [{:earmark_parser, "~> 1.4.0", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_elixir, "~> 0.14", [hex: :makeup_elixir, repo: "hexpm", optional: false]}], "hexpm", "f5e2c4702468b2fd11b10d39416ddadd2fcdd173ba2a0285ebd92c39827a5a16"}, "jason": {:hex, :jason, "1.1.2", "b03dedea67a99223a2eaf9f1264ce37154564de899fd3d8b9a21b1a6fd64afe7", [:mix], [{:decimal, "~> 1.0", [hex: :decimal, repo: "hexpm", optional: true]}], "hexpm"}, - "makeup": {:hex, :makeup, "0.8.0", "9cf32aea71c7fe0a4b2e9246c2c4978f9070257e5c9ce6d4a28ec450a839b55f", [:mix], [{:nimble_parsec, "~> 0.5.0", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "5fbc8e549aa9afeea2847c0769e3970537ed302f93a23ac612602e805d9d1e7f"}, - "makeup_elixir": {:hex, :makeup_elixir, "0.13.0", "be7a477997dcac2e48a9d695ec730b2d22418292675c75aa2d34ba0909dcdeda", [:mix], [{:makeup, "~> 0.8", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "adf0218695e22caeda2820eaba703fa46c91820d53813a2223413da3ef4ba515"}, + "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.14.1", "4f0e96847c63c17841d42c08107405a005a2680eb9c7ccadfd757bd31dabccfb", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "f2438b1a80eaec9ede832b5c41cd4f373b38fd7aa33e3b22d9db79e640cbde11"}, "mime": {:hex, :mime, "1.3.1", "30ce04ab3175b6ad0bdce0035cba77bba68b813d523d1aac73d9781b4d193cf8", [:mix], [], "hexpm"}, - "nimble_parsec": {:hex, :nimble_parsec, "0.5.0", "90e2eca3d0266e5c53f8fbe0079694740b9c91b6747f2b7e3c5d21966bba8300", [:mix], [], "hexpm", "5c040b8469c1ff1b10093d3186e2e10dbe483cd73d79ec017993fb3985b8a9b3"}, + "nimble_parsec": {:hex, :nimble_parsec, "0.6.0", "32111b3bf39137144abd7ba1cce0914533b2d16ef35e8abc5ec8be6122944263", [:mix], [], "hexpm", "27eac315a94909d4dc68bc07a4a83e06c8379237c5ea528a9acff4ca1c873c52"}, "telemetry": {:hex, :telemetry, "0.4.1", "ae2718484892448a24470e6aa341bc847c3277bfb8d4e9289f7474d752c09c7f", [:rebar3], [], "hexpm", "4738382e36a0a9a2b6e25d67c960e40e1a2c95560b9f936d8e29de8cd858480f"}, "tesla": {:hex, :tesla, "1.2.1", "864783cc27f71dd8c8969163704752476cec0f3a51eb3b06393b3971dc9733ff", [:mix], [{:exjsx, ">= 3.0.0", [hex: :exjsx, repo: "hexpm", optional: true]}, {:fuse, "~> 2.4", [hex: :fuse, repo: "hexpm", optional: true]}, {:hackney, "~> 1.6", [hex: :hackney, repo: "hexpm", optional: true]}, {:ibrowse, "~> 4.4.0", [hex: :ibrowse, repo: "hexpm", optional: true]}, {:jason, ">= 1.0.0", [hex: :jason, repo: "hexpm", optional: true]}, {:mime, "~> 1.0", [hex: :mime, repo: "hexpm", optional: false]}, {:poison, ">= 1.0.0", [hex: :poison, repo: "hexpm", optional: true]}], "hexpm"}, "testmetrics_elixir_client": {:hex, :testmetrics_elixir_client, "1.1.0", "85b80aed72f538bb0421af83fd65fd4b638f7730426145dfa9b5e17040309a18", [:mix], [{:jason, ">= 1.0.0", [hex: :jason, repo: "hexpm", optional: false]}, {:tesla, ">= 1.1.0", [hex: :tesla, repo: "hexpm", optional: false]}], "hexpm"},