From abede6c1230eef22fa6e40bb8cf90cca84bb6e8e Mon Sep 17 00:00:00 2001 From: "Kian-Meng, Ang" Date: Mon, 20 Dec 2021 13:21:46 +0800 Subject: [PATCH] Misc doc changes Besides other documentation changes, this commit includes all relevant documents to the generated HTML doc for HexDocs.pm and leverages on latest features of ExDoc. --- .formatter.exs | 2 +- .gitignore | 30 ++++++++++++++--- LICENSE => LICENSE.md | 2 +- README.md | 63 ++++++++++++++++++++++-------------- mix.exs | 42 ++++++++++++------------ mix.lock | 26 ++++++++------- test/scrivener/html_test.exs | 2 +- 7 files changed, 101 insertions(+), 66 deletions(-) rename LICENSE => LICENSE.md (97%) diff --git a/.formatter.exs b/.formatter.exs index 525446d..d2cda26 100644 --- a/.formatter.exs +++ b/.formatter.exs @@ -1,4 +1,4 @@ # Used by "mix format" [ - inputs: ["mix.exs", "{config,lib,test}/**/*.{ex,exs}"] + inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}"] ] diff --git a/.gitignore b/.gitignore index a9ce3fd..af9cec7 100644 --- a/.gitignore +++ b/.gitignore @@ -1,8 +1,30 @@ -/_build -/cover -/deps +# 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 -doc/ + +# Ignore package tarball (built via "mix hex.build"). +scrivener_html-*.tar + +# Temporary files, for example, from tests. +/tmp/ + +# Misc. .tags* .elixir_ls/ diff --git a/LICENSE b/LICENSE.md similarity index 97% rename from LICENSE rename to LICENSE.md index d34e8ac..f3ad607 100644 --- a/LICENSE +++ b/LICENSE.md @@ -1,4 +1,4 @@ -The MIT License (MIT) +# The MIT License (MIT) Copyright (c) 2015 Matt Widmann diff --git a/README.md b/README.md index 08abb6b..8342069 100644 --- a/README.md +++ b/README.md @@ -1,33 +1,39 @@ -# Scrivener.Html [![Build Status](https://semaphoreci.com/api/v1/projects/3b1ad27c-8991-4208-94d0-0bae42108482/638637/badge.svg)](https://semaphoreci.com/mgwidmann/scrivener_html) +# Scrivener.Html + +[![Build Status](https://semaphoreci.com/api/v1/projects/3b1ad27c-8991-4208-94d0-0bae42108482/638637/badge.svg)](https://semaphoreci.com/mgwidmann/scrivener_html) +[![Hex Version](https://img.shields.io/hexpm/v/scrivener_html.svg)](https://hex.pm/packages/scrivener_html) +[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/scrivener_html/) +[![Total Download](https://img.shields.io/hexpm/dt/scrivener_html.svg)](https://hex.pm/packages/scrivener_html) +[![License](https://img.shields.io/hexpm/l/scrivener_html.svg)](https://github.com/mgwidmann/scrivener_html/blob/master/LICENSE) +[![Last Updated](https://img.shields.io/github/last-commit/mgwidmann/scrivener_html.svg)](https://github.com/mgwidmann/scrivener_html/commits/master) Helpers built to work with [Scrivener](https://github.com/drewolson/scrivener)'s page struct to easily build HTML output for various CSS frameworks. ## Setup -Add to `mix.exs` +Add `:scrivener_html` to `mix.exs`: ```elixir - # add :scrivener_html to deps - defp deps do - [ - # ... - {:scrivener_html, "~> 1.8"} - # ... - ] - end - - # add :scrivener_html to applications list - defp application do - [ - # ... - applications: [ ..., :scrivener_html, ... ] - # ... - ] - end +# add :scrivener_html to deps +defp deps do + [ + # ... + {:scrivener_html, "~> 1.8"} + # ... + ] +end + +# add :scrivener_html to applications list +defp application do + [ + # ... + applications: [ ..., :scrivener_html, ... ] + # ... + ] +end ``` -For use with Phoenix.HTML, configure the `:routes_helper` module in `config/config.exs` -like the following: +For use with Phoenix.HTML, configure the `:routes_helper` module in `config/config.exs` like the following: ```elixir config :scrivener_html, @@ -36,7 +42,7 @@ config :scrivener_html, view_style: :bootstrap ``` -Import to your view. +Import to your view: ```elixir defmodule MyApp.UserView do @@ -47,7 +53,7 @@ end ## Example Usage -Use in your template. +Use in your template: ```elixir <%= for user <- @page do %> @@ -101,7 +107,7 @@ _(this would generate links like "/en/pages/1?page=1")_ ### Query String Parameters -Any additional query string parameters can be passed in as well. +Any additional query string parameters can be passed in as well: ```elixir <%= pagination_links @conn, @page, ["en"], some_parameter: "data" %> @@ -119,7 +125,7 @@ If you need to hit a different action other than `:index`, simply pass the actio ### Customizing Output -Below are the defaults which are used without passing in any options. +Below are the defaults which are used without passing in any options: ```elixir <%= pagination_links @conn, @page, [], distance: 5, next: ">>", previous: "<<", first: true, last: true, view_style: :bootstrap %> @@ -201,3 +207,10 @@ iex> Scrivener.HTML.pagination_links(%Scrivener.Page{total_pages: 10, page_numbe SEO attributes like `rel` are automatically added to pagination links. In addition, a helper for header `` tags is available (`v1.7.0` and higher) to be placed in the `` tag. See `Scrivener.HTML.SEO` documentation for more information. + +## Copyright and License + +Copyright (c) 2015 Matt Widmann + +This work is free. You can redistribute it and/or modify it under the +terms of the MIT License. See the [LICENSE.md](./LICENSE.md) file for more details. diff --git a/mix.exs b/mix.exs index 4646472..0b186d0 100644 --- a/mix.exs +++ b/mix.exs @@ -1,32 +1,25 @@ defmodule ScrivenerHtml.Mixfile do use Mix.Project + @source_url "https://github.com/mgwidmann/scrivener_html" @version "1.8.1" + def project do [ app: :scrivener_html, version: @version, elixir: "~> 1.2", name: "scrivener_html", - source_url: "https://github.com/mgwidmann/scrivener_html", - homepage_url: "https://github.com/mgwidmann/scrivener_html", elixirc_paths: elixirc_paths(Mix.env()), build_embedded: Mix.env() == :prod, start_permanent: Mix.env() == :prod, - description: "HTML helpers for Scrivener", - docs: [ - main: Scrivener.HTML, - readme: "README.md" - ], package: package(), deps: deps(), + docs: docs(), aliases: aliases() ] end - # Configuration for the OTP application - # - # Type `mix help compile.app` for more information def application do [ applications: [:logger] @@ -36,31 +29,36 @@ defmodule ScrivenerHtml.Mixfile do defp elixirc_paths(:test), do: ["lib", "test/support"] defp elixirc_paths(_), do: ["lib"] - # 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 [ {:scrivener, "~> 1.2 or ~> 2.0"}, {:phoenix_html, "~> 2.2"}, {:phoenix, "~> 1.0 and < 1.5.0", optional: true}, {:plug, "~> 1.1"}, - {:ex_doc, "~> 0.19", only: :dev}, - {:earmark, "~> 1.1", only: :dev} + {:ex_doc, ">= 0.0.0", only: :dev, runtime: false} ] end defp package do [ + description: "HTML helpers for Scrivener", maintainers: ["Matt Widmann"], licenses: ["MIT"], - links: %{github: "https://github.com/mgwidmann/scrivener_html"} + links: %{GitHub: @source_url} + ] + end + + defp docs do + [ + extras: [ + "LICENSE.md": [title: "License"], + "README.md": [title: "Overview"] + ], + main: "readme", + homepage_url: @source_url, + source_url: @source_url, + source_ref: "v#{@version}", + formatters: ["html"] ] end diff --git a/mix.lock b/mix.lock index 60a41fe..a00a496 100644 --- a/mix.lock +++ b/mix.lock @@ -1,20 +1,22 @@ %{ "decimal": {:hex, :decimal, "1.1.2", "79a769d4657b2d537b51ef3c02d29ab7141d2b486b516c109642d453ee08e00c", [:mix], []}, - "earmark": {:hex, :earmark, "1.3.1", "73812f447f7a42358d3ba79283cfa3075a7580a3a2ed457616d6517ac3738cb9", [:mix], [], "hexpm"}, + "earmark": {:hex, :earmark, "1.3.1", "73812f447f7a42358d3ba79283cfa3075a7580a3a2ed457616d6517ac3738cb9", [:mix], [], "hexpm", "000aaeff08919e95e7aea13e4af7b2b9734577b3e6a7c50ee31ee88cab6ec4fb"}, + "earmark_parser": {:hex, :earmark_parser, "1.4.18", "e1b2be73eb08a49fb032a0208bf647380682374a725dfb5b9e510def8397f6f2", [:mix], [], "hexpm", "114a0e85ec3cf9e04b811009e73c206394ffecfcc313e0b346de0d557774ee97"}, "ecto": {:hex, :ecto, "1.1.8", "0f0348e678fa5a450c266d69816808f97fbd82ade32cf88d4b09bbe8f8c27545", [:mix], [{:decimal, "~> 1.0", [hex: :decimal, optional: false]}, {:mariaex, "~> 0.5.0 or ~> 0.6.0", [hex: :mariaex, optional: true]}, {:poison, "~> 1.0 or ~> 2.0", [hex: :poison, optional: true]}, {:poolboy, "~> 1.4", [hex: :poolboy, optional: false]}, {:postgrex, "~> 0.11.0", [hex: :postgrex, optional: true]}, {:sbroker, "~> 0.7", [hex: :sbroker, optional: true]}]}, - "ex_doc": {:hex, :ex_doc, "0.19.3", "3c7b0f02851f5fc13b040e8e925051452e41248f685e40250d7e40b07b9f8c10", [:mix], [{:earmark, "~> 1.2", [hex: :earmark, repo: "hexpm", optional: false]}, {:makeup_elixir, "~> 0.10", [hex: :makeup_elixir, repo: "hexpm", optional: false]}], "hexpm"}, - "makeup": {:hex, :makeup, "0.8.0", "9cf32aea71c7fe0a4b2e9246c2c4978f9070257e5c9ce6d4a28ec450a839b55f", [:mix], [{:nimble_parsec, "~> 0.5.0", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm"}, - "makeup_elixir": {:hex, :makeup_elixir, "0.13.0", "be7a477997dcac2e48a9d695ec730b2d22418292675c75aa2d34ba0909dcdeda", [:mix], [{:makeup, "~> 0.8", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm"}, + "ex_doc": {:hex, :ex_doc, "0.26.0", "1922164bac0b18b02f84d6f69cab1b93bc3e870e2ad18d5dacb50a9e06b542a3", [: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", "2775d66e494a9a48355db7867478ffd997864c61c65a47d31c4949459281c78d"}, + "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.2", "dc72dfe17eb240552857465cc00cce390960d9a0c055c4ccd38b70629227e97c", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.1", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "fd23ae48d09b32eff49d4ced2b43c9f086d402ee4fd4fcb2d7fad97fa8823e75"}, + "makeup_erlang": {:hex, :makeup_erlang, "0.1.1", "3fcb7f09eb9d98dc4d208f49cc955a34218fc41ff6b84df7c75b3e6e533cc65f", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "174d0809e98a4ef0b3309256cbf97101c6ec01c4ab0b23e926a9e17df2077cbb"}, "meck": {:hex, :meck, "0.8.4", "59ca1cd971372aa223138efcf9b29475bde299e1953046a0c727184790ab1520", [:rebar, :make], []}, - "mime": {:hex, :mime, "1.3.0", "5e8d45a39e95c650900d03f897fbf99ae04f60ab1daa4a34c7a20a5151b7a5fe", [:mix], [], "hexpm"}, - "nimble_parsec": {:hex, :nimble_parsec, "0.5.0", "90e2eca3d0266e5c53f8fbe0079694740b9c91b6747f2b7e3c5d21966bba8300", [:mix], [], "hexpm"}, + "mime": {:hex, :mime, "1.3.0", "5e8d45a39e95c650900d03f897fbf99ae04f60ab1daa4a34c7a20a5151b7a5fe", [:mix], [], "hexpm", "5e839994289d60326aa86020c4fbd9c6938af188ecddab2579f07b66cd665328"}, + "nimble_parsec": {:hex, :nimble_parsec, "1.2.0", "b44d75e2a6542dcb6acf5d71c32c74ca88960421b6874777f79153bbbbd7dccc", [:mix], [], "hexpm", "52b2871a7515a5ac49b00f214e4165a40724cf99798d8e4a65e4fd64ebd002c1"}, "pavlov": {:git, "https://github.com/sproutapp/pavlov.git", "7f3c0d7c75c8c2875e21b495511a291194bfc85a", []}, - "phoenix": {:hex, :phoenix, "1.4.0", "56fe9a809e0e735f3e3b9b31c1b749d4b436e466d8da627b8d82f90eaae714d2", [:mix], [{:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: true]}, {:phoenix_pubsub, "~> 1.1", [hex: :phoenix_pubsub, repo: "hexpm", optional: false]}, {:plug, "~> 1.7", [hex: :plug, repo: "hexpm", optional: false]}, {:plug_cowboy, "~> 1.0 or ~> 2.0", [hex: :plug_cowboy, repo: "hexpm", optional: true]}], "hexpm"}, - "phoenix_html": {:hex, :phoenix_html, "2.9.3", "1b5a2122cbf743aa242f54dced8a4f1cc778b8bd304f4b4c0043a6250c58e258", [:mix], [{:plug, "~> 1.0", [hex: :plug, optional: false]}]}, - "phoenix_pubsub": {:hex, :phoenix_pubsub, "1.1.1", "6668d787e602981f24f17a5fbb69cc98f8ab085114ebfac6cc36e10a90c8e93c", [:mix], [], "hexpm"}, - "plug": {:hex, :plug, "1.7.1", "8516d565fb84a6a8b2ca722e74e2cd25ca0fc9d64f364ec9dbec09d33eb78ccd", [:mix], [{:mime, "~> 1.0", [hex: :mime, repo: "hexpm", optional: false]}, {:plug_crypto, "~> 1.0", [hex: :plug_crypto, repo: "hexpm", optional: false]}], "hexpm"}, - "plug_crypto": {:hex, :plug_crypto, "1.0.0", "18e49317d3fa343f24620ed22795ec29d4a5e602d52d1513ccea0b07d8ea7d4d", [:mix], [], "hexpm"}, + "phoenix": {:hex, :phoenix, "1.4.0", "56fe9a809e0e735f3e3b9b31c1b749d4b436e466d8da627b8d82f90eaae714d2", [:mix], [{:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: true]}, {:phoenix_pubsub, "~> 1.1", [hex: :phoenix_pubsub, repo: "hexpm", optional: false]}, {:plug, "~> 1.7", [hex: :plug, repo: "hexpm", optional: false]}, {:plug_cowboy, "~> 1.0 or ~> 2.0", [hex: :plug_cowboy, repo: "hexpm", optional: true]}], "hexpm", "22da8f659cf13d3ba73b767f66b8c389113ddf0ef7b94225cc84e94b85eac90e"}, + "phoenix_html": {:hex, :phoenix_html, "2.9.3", "1b5a2122cbf743aa242f54dced8a4f1cc778b8bd304f4b4c0043a6250c58e258", [:mix], [{:plug, "~> 1.0", [hex: :plug, repo: "hexpm", optional: false]}], "hexpm", "f090e3a75de4efd72ae2b9b016909fe673512ef04e6b72d7bf039031a64d4a52"}, + "phoenix_pubsub": {:hex, :phoenix_pubsub, "1.1.1", "6668d787e602981f24f17a5fbb69cc98f8ab085114ebfac6cc36e10a90c8e93c", [:mix], [], "hexpm", "a3d890aaa3156d51056179dcaaadaf32b844f71656bb27c58756f2b97875c36c"}, + "plug": {:hex, :plug, "1.7.1", "8516d565fb84a6a8b2ca722e74e2cd25ca0fc9d64f364ec9dbec09d33eb78ccd", [:mix], [{:mime, "~> 1.0", [hex: :mime, repo: "hexpm", optional: false]}, {:plug_crypto, "~> 1.0", [hex: :plug_crypto, repo: "hexpm", optional: false]}], "hexpm", "daa5fee4209c12c3c48b05a96cf88c320b627c9575f987554dcdc1fdcdf2c15e"}, + "plug_crypto": {:hex, :plug_crypto, "1.0.0", "18e49317d3fa343f24620ed22795ec29d4a5e602d52d1513ccea0b07d8ea7d4d", [:mix], [], "hexpm", "73c1682f0e414cfb5d9b95c8e8cd6ffcfdae699e3b05e1db744e58b7be857759"}, "poison": {:hex, :poison, "2.2.0", "4763b69a8a77bd77d26f477d196428b741261a761257ff1cf92753a0d4d24a63", [:mix], [], "hexpm"}, "poolboy": {:hex, :poolboy, "1.5.1", "6b46163901cfd0a1b43d692657ed9d7e599853b3b21b95ae5ae0a777cf9b6ca8", [:rebar], []}, - "scrivener": {:hex, :scrivener, "2.2.1", "5a84cdfc042e3c318a03f965d8197b8294676a8fff7c4a29e482a90c467ebf19", [:mix], []}, + "scrivener": {:hex, :scrivener, "2.2.1", "5a84cdfc042e3c318a03f965d8197b8294676a8fff7c4a29e482a90c467ebf19", [:mix], [], "hexpm", "a9cc85e580925b13cdb5265cead4594ddb3cc7fb23eea8843c219827165f6c4f"}, } diff --git a/test/scrivener/html_test.exs b/test/scrivener/html_test.exs index 480c910..7ed4178 100644 --- a/test/scrivener/html_test.exs +++ b/test/scrivener/html_test.exs @@ -289,7 +289,7 @@ defmodule Scrivener.HTMLTest do |> String.trim_trailing() end - test "accept nested keyword list for additionnal params" do + test "accept nested keyword list for additional params" do html = HTML.pagination_links(%Page{total_pages: 2, page_number: 2}, q: [name: "joe"]) assert Phoenix.HTML.safe_to_string(html) =~ ~r(q\[name\]=joe) end