From 913ff76bfb59b8567aabeae6a879deb7ea7e99a7 Mon Sep 17 00:00:00 2001 From: Kian-Meng Ang Date: Fri, 2 Jul 2021 00:29:13 +0800 Subject: [PATCH] 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. --- .formatter.exs | 4 ++ .gitignore | 30 +++++++++--- README.md | 49 ++++++++++++------- lib/kerosene/html.ex | 17 ++++--- mix.exs | 109 +++++++++++++++++++++++++------------------ mix.lock | 33 +++++++------ 6 files changed, 154 insertions(+), 88 deletions(-) create mode 100644 .formatter.exs diff --git a/.formatter.exs b/.formatter.exs new file mode 100644 index 0000000..d2cda26 --- /dev/null +++ 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 index 446d0ae..e994c20 100644 --- a/.gitignore +++ b/.gitignore @@ -1,10 +1,26 @@ -/_build -/cover -/deps -/docs -/doc -*.tar +# 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 -tags +# Ignore package tarball (built via "mix hex.build"). +kerosene-*.tar + +# Temporary files, for example, from tests. +/tmp/ diff --git a/README.md b/README.md index 0fdb7be..6bcf0fe 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,11 @@ # Kerosene +[![Module Version](https://img.shields.io/hexpm/v/kerosene.svg)](https://hex.pm/packages/kerosene) +[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/kerosene/) +[![Total Download](https://img.shields.io/hexpm/dt/kerosene.svg)](https://hex.pm/packages/kerosene) +[![License](https://img.shields.io/hexpm/l/kerosene.svg)](https://github.com/elixirdrops/kerosene/blob/master/LICENSE.md) +[![Last Updated](https://img.shields.io/github/last-commit/elixirdrops/kerosene.svg)](https://github.com/elixirdrops/kerosene/commits/master) + Pagination for Ecto and Phoenix. @@ -7,17 +13,21 @@ Pagination for Ecto and Phoenix. The package is [available in Hex](https://hex.pm/packages/kerosene), the package can be installed as: -Add kerosene to your list of dependencies in `mix.exs`: +Add `:kerosene` to your list of dependencies in `mix.exs`: + ```elixir def deps do - [{:kerosene, "~> 0.9.0"}] + [ + {:kerosene, "~> 0.9.0"} + ] end ``` -Add Kerosene to your `repo.ex`: +Add `:kerosene` to your `repo.ex`: + ```elixir defmodule MyApp.Repo do - use Ecto.Repo, + use Ecto.Repo, otp_app: :testapp, adapter: Ecto.Adapters.Postgres use Kerosene, per_page: 2 @@ -25,10 +35,12 @@ end ``` ## Usage -Start paginating your queries + +Start paginating your queries: + ```elixir def index(conn, params) do - {products, kerosene} = + {products, kerosene} = Product |> Product.with_lowest_price |> Repo.paginate(params) @@ -37,7 +49,8 @@ def index(conn, params) do end ``` -Add view helpers to your view +Add view helpers to your view: + ```elixir defmodule MyApp.ProductView do use MyApp.Web, :view @@ -45,24 +58,27 @@ defmodule MyApp.ProductView do end ``` -Generate the links using the view helpers +Generate the links using the view helpers: + ```elixir <%= paginate @conn, @kerosene %> ``` -Kerosene provides a [list ](https://hexdocs.pm/kerosene/Kerosene.HTML.html#__using__/1) of themes for pagination. By default it uses bootstrap. To use some other, add to config/config.exs: +Kerosene provides a [list ](https://hexdocs.pm/kerosene/Kerosene.HTML.html#__using__/1) of themes for pagination. By default it uses bootstrap. To use some other, add to `config/config.exs`: + ```elixir config :kerosene, theme: :foundation ``` If you need reduced number of links in pagination, you can use `simple mode` option, to display only Prev/Next links: + ```elixir config :kerosene, mode: :simple ``` -Building apis or SPA's, no problem Kerosene has support for Json. +Building APIs or SPA's, no problem Kerosene has support for JSON. ```elixir defmodule MyApp.ProductView do @@ -83,15 +99,13 @@ defmodule MyApp.ProductView do end ``` - You can also send in options to paginate helper look at the docs for more details. ## Contributing - -Please do send pull requests and bug reports, positive feedback is always welcome. +Please do send pull requests and bug reports, positive feedback is always welcome. -## Acknowledgement +## Acknowledgment I would like to Thank @@ -99,6 +113,9 @@ I would like to Thank * Drew Olson (@drewolson) * Akira Matsuda (@amatsuda) -## License +## Copyright and License + +Copyright (c) 2014 Ally Raza -Please take a look at LICENSE.md +Released under the MIT License, which can be found in the repository in +[LICENSE.md](./LICENSE.md). diff --git a/lib/kerosene/html.ex b/lib/kerosene/html.ex index 573ec64..8246e04 100644 --- a/lib/kerosene/html.ex +++ b/lib/kerosene/html.ex @@ -20,7 +20,11 @@ defmodule Kerosene.HTML do Where `@page` is a `%Kerosene{}` struct returned from `Repo.paginate/2`. `paginate` helper takes keyword list of `options` and `params`. - <%= paginate @conn, @page, window: 5, next_label: ">>", previous_label: "<<", first: true, last: true, first_label: "First", last_label: "Last" %> + + <%= paginate @conn, @page, window: 5, + next_label: ">>", previous_label: "<<", first: true, last: true, + first_label: "First", last_label: "Last" %> + """ @doc """ @@ -32,19 +36,20 @@ defmodule Kerosene.HTML do #{inspect @themes} - Example: + ## Examples iex> Kerosene.HTML.paginate(@conn, @kerosene) Path can be overriden by adding setting `:path` in the `opts`. For example: - Kerosene.HTML.paginate(@conn, @kerosene, path: product_path(@conn, :index, foo: "bar")) + iex> Kerosene.HTML.paginate(@conn, @kerosene, path: product_path(@conn, :index, foo: "bar")) Additional panigation class can be added by adding setting `:class` in the `opts`. For example: - Kerosene.HTML.paginate(@conn, @kerosene, theme: :boostrap4, class: "paginate-sm") + iex> Kerosene.HTML.paginate(@conn, @kerosene, theme: :boostrap4, class: "paginate-sm") + """ defmacro __using__(_opts \\ []) do quote do @@ -55,8 +60,8 @@ defmodule Kerosene.HTML do def paginate(conn, paginator, opts \\ []) do opts = build_options(opts) - conn - |> Kerosene.Paginator.paginate(paginator, opts) + conn + |> Kerosene.Paginator.paginate(paginator, opts) |> render_page_list(opts) end diff --git a/mix.exs b/mix.exs index e99ba0f..1c32324 100644 --- a/mix.exs +++ b/mix.exs @@ -1,70 +1,89 @@ defmodule Kerosene.Mixfile do use Mix.Project + + @source_url "https://github.com/elixirdrops/kerosene" @version "0.9.0" def project do - [app: :kerosene, - version: @version, - elixir: "~> 1.2", - elixirc_paths: path(Mix.env), - package: package(), - build_embedded: Mix.env == :prod, - start_permanent: Mix.env == :prod, - deps: deps(), - aliases: aliases(), - name: "Kerosene", - docs: [source_ref: "v#{@version}", main: "Kerosene"], - source_url: "https://github.com/elixirdrops/kerosene", - description: """ - Pagination for Ecto and Phoenix. - """] + [ + app: :kerosene, + version: @version, + elixir: "~> 1.2", + name: "Kerosene", + elixirc_paths: path(Mix.env()), + build_embedded: Mix.env() == :prod, + start_permanent: Mix.env() == :prod, + package: package(), + deps: deps(), + docs: docs(), + aliases: aliases(), + preferred_cli_env: preferred_cli_env() + ] end - # Configuration for the OTP application - # - # Type "mix help compile.app" for more information def application do - [applications: application(Mix.env)] + [ + applications: application(Mix.env()) + ] end + defp application(:test), do: [:postgrex, :ecto, :logger] defp application(_), do: [:logger] - # Dependencies can be Hex packages: - # - # {:mydep, "~> 0.3.0"} - # - # Or git/path repositories: - # - # {:mydep, git: "https://github.com/elixir-lang/mydep.git", tag: "0.1.0"} - # - # Type "mix help deps" for more examples and options defp deps do - [{:phoenix_html, "~> 2.10"}, - {:plug, "~> 1.4"}, - {:ecto, "~> 3.0"}, - {:ecto_sql, "~> 3.0"}, - # Test dependencies - {:postgrex, "~> 0.14.0", only: [:test]}, - # Docs dependencies - {:earmark, "~> 0.1", only: :docs}, - {:ex_doc, "~> 0.11", only: :docs}, - {:inch_ex, "~> 0.2", only: :docs}] + [ + {:ecto, "~> 3.0"}, + {:ecto_sql, "~> 3.0"}, + {:ex_doc, ">= 0.0.0", only: :docs, runtime: false}, + {:inch_ex, "~> 0.2", only: :docs, runtime: false}, + {:phoenix_html, "~> 2.10"}, + {:plug, "~> 1.4"}, + {:postgrex, "~> 0.14.0", only: [:test]} + ] end defp path(:test) do ["lib", "test/support", "test/fixtures"] end + defp path(_), do: ["lib"] defp package do - [maintainers: ["Ally Raza"], - licenses: ["MIT"], - links: %{github: "https://github.com/elixirdrops/kerosene"}, - files: ~w(lib test config) ++ - ~w(CHANGELOG.md LICENSE.md mix.exs README.md)] + [ + description: "Pagination for Ecto and Phoenix.", + maintainers: ["Ally Raza"], + licenses: ["MIT"], + files: + ~w(lib test config) ++ + ~w(CHANGELOG.md LICENSE.md mix.exs README.md), + links: %{ + GitHub: @source_url + } + ] + end + + defp aliases do + [ + test: ["ecto.create --quite", "ecto.migrate --quite", "test"] + ] + end + + defp preferred_cli_env do + [ + docs: :docs + ] end - def aliases do - [test: ["ecto.create --quite", "ecto.migrate --quite", "test"]] + defp docs do + [ + extras: [ + "CHANGELOG.md": [title: "Changelog"], + "LICENSE.md": [title: "License"], + "README.md": [title: "Overview"] + ], + main: "readme", + source_ref: "v#{@version}", + formatters: ["html"] + ] end end diff --git a/mix.lock b/mix.lock index 7518900..42b4d28 100644 --- a/mix.lock +++ b/mix.lock @@ -1,16 +1,21 @@ %{ - "connection": {:hex, :connection, "1.0.4", "a1cae72211f0eef17705aaededacac3eb30e6625b04a6117c1b2db6ace7d5976", [:mix], []}, - "db_connection": {:hex, :db_connection, "2.0.1", "09454c6c6e8e4295f400b72580b19f0ac68fda2602e209533285206cb99bee6b", [:mix], [{:connection, "~> 1.0.2", [hex: :connection, repo: "hexpm", optional: false]}], "hexpm"}, - "decimal": {:hex, :decimal, "1.5.0", "b0433a36d0e2430e3d50291b1c65f53c37d56f83665b43d79963684865beab68", [:mix], [], "hexpm"}, - "earmark": {:hex, :earmark, "0.2.1", "ba6d26ceb16106d069b289df66751734802777a3cbb6787026dd800ffeb850f3", [:mix], []}, - "ecto": {:hex, :ecto, "3.0.0", "059250d96f17f9c10f524fcb09d058f566691343e90318a161cf62a48f3912a9", [:mix], [{:decimal, "~> 1.5", [hex: :decimal, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: true]}, {:poison, "~> 2.2 or ~> 3.0", [hex: :poison, repo: "hexpm", optional: true]}], "hexpm"}, - "ecto_sql": {:hex, :ecto_sql, "3.0.0", "8d1883376bee02a0e76b5ef797e39d04333c34b9935d0b4785dbf3cbdb571e2a", [:mix], [{:db_connection, "~> 2.0", [hex: :db_connection, repo: "hexpm", optional: false]}, {:ecto, "~> 3.0.0", [hex: :ecto, repo: "hexpm", optional: false]}, {:mariaex, "~> 0.9.0", [hex: :mariaex, repo: "hexpm", optional: true]}, {:postgrex, "~> 0.14.0", [hex: :postgrex, repo: "hexpm", optional: true]}, {:telemetry, "~> 0.2.0", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm"}, - "ex_doc": {:hex, :ex_doc, "0.12.0", "b774aabfede4af31c0301aece12371cbd25995a21bb3d71d66f5c2fe074c603f", [:mix], [{:earmark, "~> 0.2", [hex: :earmark, optional: false]}]}, - "inch_ex": {:hex, :inch_ex, "0.5.5", "b63f57e281467bd3456461525fdbc9e158c8edbe603da6e3e4671befde796a3d", [:mix], [{:poison, "~> 1.5 or ~> 2.0 or ~> 3.0", [hex: :poison, optional: false]}]}, - "mime": {:hex, :mime, "1.1.0", "01c1d6f4083d8aa5c7b8c246ade95139620ef8effb009edde934e0ec3b28090a", [:mix], []}, - "phoenix_html": {:hex, :phoenix_html, "2.10.4", "d4f99c32d5dc4918b531fdf163e1fd7cf20acdd7703f16f5d02d4db36de803b7", [:mix], [{:plug, "~> 1.0", [hex: :plug, optional: false]}]}, - "plug": {:hex, :plug, "1.4.3", "236d77ce7bf3e3a2668dc0d32a9b6f1f9b1f05361019946aae49874904be4aed", [:mix], [{:cowboy, "~> 1.0.1 or ~> 1.1", [hex: :cowboy, optional: true]}, {:mime, "~> 1.0", [hex: :mime, optional: false]}]}, - "poison": {:hex, :poison, "3.1.0", "d9eb636610e096f86f25d9a46f35a9facac35609a7591b3be3326e99a0484665", [:mix], []}, - "postgrex": {:hex, :postgrex, "0.14.0", "f3d6ffea1ca8a156e0633900a5338a3d17b00435227726baed8982718232b694", [:mix], [{:connection, "~> 1.0", [hex: :connection, repo: "hexpm", optional: false]}, {:db_connection, "~> 2.0", [hex: :db_connection, repo: "hexpm", optional: false]}, {:decimal, "~> 1.0", [hex: :decimal, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: true]}], "hexpm"}, - "telemetry": {:hex, :telemetry, "0.2.0", "5b40caa3efe4deb30fb12d7cd8ed4f556f6d6bd15c374c2366772161311ce377", [:mix], [], "hexpm"}, + "connection": {:hex, :connection, "1.0.4", "a1cae72211f0eef17705aaededacac3eb30e6625b04a6117c1b2db6ace7d5976", [:mix], [], "hexpm", "4a0850c9be22a43af9920a71ab17c051f5f7d45c209e40269a1938832510e4d9"}, + "db_connection": {:hex, :db_connection, "2.0.1", "09454c6c6e8e4295f400b72580b19f0ac68fda2602e209533285206cb99bee6b", [:mix], [{:connection, "~> 1.0.2", [hex: :connection, repo: "hexpm", optional: false]}], "hexpm", "aad7a9a85a778a798b734a41dcbfb99fbe291e329549a68330e1c5b0865c31f8"}, + "decimal": {:hex, :decimal, "1.5.0", "b0433a36d0e2430e3d50291b1c65f53c37d56f83665b43d79963684865beab68", [:mix], [], "hexpm", "130926580655f34d759dd25f5d723fd233c9bbe0399cde57e2a1adea9ed92e08"}, + "earmark": {:hex, :earmark, "0.2.1", "ba6d26ceb16106d069b289df66751734802777a3cbb6787026dd800ffeb850f3", [:mix], [], "hexpm", "c86afb8d22a5aa8315afd4257c7512011c0c9a48b0fea43af7612836b958098b"}, + "earmark_parser": {:hex, :earmark_parser, "1.4.13", "0c98163e7d04a15feb62000e1a891489feb29f3d10cb57d4f845c405852bbef8", [:mix], [], "hexpm", "d602c26af3a0af43d2f2645613f65841657ad6efc9f0e361c3b6c06b578214ba"}, + "ecto": {:hex, :ecto, "3.0.0", "059250d96f17f9c10f524fcb09d058f566691343e90318a161cf62a48f3912a9", [:mix], [{:decimal, "~> 1.5", [hex: :decimal, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: true]}, {:poison, "~> 2.2 or ~> 3.0", [hex: :poison, repo: "hexpm", optional: true]}], "hexpm", "e425bac0b6a7796655395deaf411f32f9fd8133c65eb2977ec370889e4705a9c"}, + "ecto_sql": {:hex, :ecto_sql, "3.0.0", "8d1883376bee02a0e76b5ef797e39d04333c34b9935d0b4785dbf3cbdb571e2a", [:mix], [{:db_connection, "~> 2.0", [hex: :db_connection, repo: "hexpm", optional: false]}, {:ecto, "~> 3.0.0", [hex: :ecto, repo: "hexpm", optional: false]}, {:mariaex, "~> 0.9.0", [hex: :mariaex, repo: "hexpm", optional: true]}, {:postgrex, "~> 0.14.0", [hex: :postgrex, repo: "hexpm", optional: true]}, {:telemetry, "~> 0.2.0", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm", "6fa4c5d69c4fd5be1a1a28fdc0fe98c8d9277eeb505c6da8f316d01330fa56e1"}, + "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"}, + "inch_ex": {:hex, :inch_ex, "0.5.5", "b63f57e281467bd3456461525fdbc9e158c8edbe603da6e3e4671befde796a3d", [:mix], [{:poison, "~> 1.5 or ~> 2.0 or ~> 3.0", [hex: :poison, repo: "hexpm", optional: false]}], "hexpm", "9c2e35eb4189db5fe3448d1e2b98b0802a3e83a63e39e137c04d09ef1450f636"}, + "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"}, + "makeup_erlang": {:hex, :makeup_erlang, "0.1.1", "3fcb7f09eb9d98dc4d208f49cc955a34218fc41ff6b84df7c75b3e6e533cc65f", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "174d0809e98a4ef0b3309256cbf97101c6ec01c4ab0b23e926a9e17df2077cbb"}, + "mime": {:hex, :mime, "1.1.0", "01c1d6f4083d8aa5c7b8c246ade95139620ef8effb009edde934e0ec3b28090a", [:mix], [], "hexpm", "33dd09e615daab5668c15cc3a33829892728fdbed910ab0c0a0edb06b45fc54d"}, + "nimble_parsec": {:hex, :nimble_parsec, "1.1.0", "3a6fca1550363552e54c216debb6a9e95bd8d32348938e13de5eda962c0d7f89", [:mix], [], "hexpm", "08eb32d66b706e913ff748f11694b17981c0b04a33ef470e33e11b3d3ac8f54b"}, + "phoenix_html": {:hex, :phoenix_html, "2.10.4", "d4f99c32d5dc4918b531fdf163e1fd7cf20acdd7703f16f5d02d4db36de803b7", [:mix], [{:plug, "~> 1.0", [hex: :plug, repo: "hexpm", optional: false]}], "hexpm", "768bb3d99938342a46d5c8fb22b35c0668f9349030a23206dd690da267a3dcc8"}, + "plug": {:hex, :plug, "1.4.3", "236d77ce7bf3e3a2668dc0d32a9b6f1f9b1f05361019946aae49874904be4aed", [:mix], [{:cowboy, "~> 1.0.1 or ~> 1.1", [hex: :cowboy, repo: "hexpm", optional: true]}, {:mime, "~> 1.0", [hex: :mime, repo: "hexpm", optional: false]}], "hexpm", "c1c408c57a1e4c88c365b9aff1198c350e22b765dbb97a460e9e6bd9364c6194"}, + "poison": {:hex, :poison, "3.1.0", "d9eb636610e096f86f25d9a46f35a9facac35609a7591b3be3326e99a0484665", [:mix], [], "hexpm", "fec8660eb7733ee4117b85f55799fd3833eb769a6df71ccf8903e8dc5447cfce"}, + "postgrex": {:hex, :postgrex, "0.14.0", "f3d6ffea1ca8a156e0633900a5338a3d17b00435227726baed8982718232b694", [:mix], [{:connection, "~> 1.0", [hex: :connection, repo: "hexpm", optional: false]}, {:db_connection, "~> 2.0", [hex: :db_connection, repo: "hexpm", optional: false]}, {:decimal, "~> 1.0", [hex: :decimal, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: true]}], "hexpm", "ee6d8bc31ec7064f87030b98e431cf7ef0537052339de289b575b0a8872f501e"}, + "telemetry": {:hex, :telemetry, "0.2.0", "5b40caa3efe4deb30fb12d7cd8ed4f556f6d6bd15c374c2366772161311ce377", [:mix], [], "hexpm", "4e9071b8d1795d0f1ae00584594c3faf430c88821b69e4bd09b02e7840231f32"}, }