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.
2025-03-13 12:04:57 -04:00 · 2021-08-30 23:08:45 +08:00 · 2021-08-30 23:08:45 +08:00 · 3b7d5d5eea
commit 3b7d5d5eea
parent b09754cae3
11 changed files with 111 additions and 63 deletions
--- a/.formatter.exs
+++ b/.formatter.exs
@ -0,0 +1,4 @@
+# Used by "mix format"
+[
+  inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}"]
+]
--- a/.gitignore
+++ b/.gitignore
@ -1,6 +1,26 @@
-/_build
-/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
-.elixir_ls
+
+# Ignore package tarball (built via "mix hex.build").
+httparrot-*.tar
+
+# Temporary files, for example, from tests.
+/tmp/
--- a/LICENSE.md
+++ b/LICENSE.md
@ -1,4 +1,6 @@
-Copyright (c) 2013-2014 Eduardo Gurgel Pinho
+# The MIT License
+
+Copyright (c) 2013 Eduardo Gurgel <eduardo@gurgel.me>

 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the
--- a/README.md
+++ b/README.md
@ -1,49 +1,56 @@
-# HTTParrot [![Build Status](https://travis-ci.org/edgurgel/httparrot.png?branch=master)](https://travis-ci.org/edgurgel/httparrot)
+# HTTParrot

-HTTP server built on top of Cowboy using (mostly) `cowboy_rest` handlers to serve useful endpoints for testing purposes. Its goal is to be as close as possible to [HTTPBin](http://httpbin.org).
+[![Build Status](https://travis-ci.org/edgurgel/httparrot.png?branch=master)](https://travis-ci.org/edgurgel/httparrot)
+[![Module Version](https://img.shields.io/hexpm/v/httparrot.svg)](https://hex.pm/packages/httparrot)
+[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/httparrot/)
+[![Total Download](https://img.shields.io/hexpm/dt/httparrot.svg)](https://hex.pm/packages/httparrot)
+[![License](https://img.shields.io/hexpm/l/httparrot.svg)](https://github.com/edgurgel/httparrot/blob/master/LICENSE.md)
+[![Last Updated](https://img.shields.io/github/last-commit/edgurgel/httparrot.svg)](https://github.com/edgurgel/httparrot/commits/master)
+
+HTTP server built on top of [Cowboy](https://hex.pm/packages/cowboy) using (mostly) `cowboy_rest` handlers to serve useful endpoints for testing purposes. Its goal is to be as close as possible to [HTTPBin](http://httpbin.org).

 ## Endpoints

-* / This page.
-* /ip Returns Origin IP.
-* /user-agent Returns user-agent.
-* /headers Returns header dict.
-* /get Returns GET data.
-* /post Returns POST data.
-* /put Returns PUT data.
-* /patch Returns PATCH data.
-* /delete Returns DELETE data
-* /gzip Returns gzip-encoded data.
-* /status/:code Returns given HTTP Status code.
-* /response-headers?key=val Returns given response headers.
-* /redirect/:n 301 Redirects n times.
-* /redirect-to?url=foo 301 Redirects to the foo URL.
-* /relative-redirect/:n 301 Relative redirects n times.
-* /cookies Returns cookie data.
-* /cookies/set?name=value Sets one or more simple cookies.
-* /cookies/set/name/value Sets one cookie .
-* /cookies/delete?name Deletes one or more simple cookies.
-* /basic-auth/:user/:passwd Challenges HTTPBasic Auth.
-* /hidden-basic-auth/:user/:passwd 404'd BasicAuth.
-* /digest-auth/:qop/:user/:passwd Challenges HTTP Digest Auth.
-* /stream/:n Streams n–100 lines.
-* /delay/:n Delays responding for n–10 seconds.
-* /html Renders an HTML Page.
-* /robots.txt Returns some robots.txt rules.
-* /deny Denied by robots.txt file.
-* /cache Returns 200 unless an If-Modified-Since header is provided, when it returns a 304 Not Modified.
-* /base64/:value Decodes base64url-encoded string.
-* /image Return an image based on Accept header.
-* /websocket Echo message received through websocket
+* `/` This page.
+* `/ip` Returns Origin IP.
+* `/user-agent` Returns user-agent.
+* `/headers` Returns header dict.
+* `/get` Returns GET data.
+* `/post` Returns POST data.
+* `/put` Returns PUT data.
+* `/patch` Returns PATCH data.
+* `/delete` Returns DELETE data
+* `/gzip` Returns gzip-encoded data.
+* `/status/:code` Returns given HTTP Status code.
+* `/response-headers?key=val` Returns given response headers.
+* `/redirect/:n` 301 Redirects n times.
+* `/redirect-to?url=foo` 301 Redirects to the foo URL.
+* `/relative-redirect/:n` 301 Relative redirects n times.
+* `/cookies` Returns cookie data.
+* `/cookies/set?name=value` Sets one or more simple cookies.
+* `/cookies/set/name/value` Sets one cookie .
+* `/cookies/delete?name` Deletes one or more simple cookies.
+* `/basic-auth/:user/:passwd` Challenges HTTPBasic Auth.
+* `/hidden-basic-auth/:user/:passwd` 404'd BasicAuth.
+* `/digest-auth/:qop/:user/:passwd` Challenges HTTP Digest Auth.
+* `/stream/:n` Streams n–100 lines.
+* `/delay/:n` Delays responding for n–10 seconds.
+* `/html` Renders an HTML Page.
+* `/robots.txt` Returns some robots.txt rules.
+* `/deny` Denied by robots.txt file.
+* `/cache` Returns 200 unless an If-Modified-Since header is provided, when it returns a 304 Not Modified.
+* `/base64/:value` Decodes base64url-encoded string.
+* `/image` Return an image based on Accept header.
+* `/websocket` Echo message received through websocket

 ## TODO

-* [ ] /deflate Returns deflate-encoded data.
-* [ ] /digest-auth/:qop/:user/:passwd Challenges HTTP Digest Auth.
+* [ ] `/deflate` Returns deflate-encoded data.
+* [ ] `/digest-auth/:qop/:user/:passwd` Challenges HTTP Digest Auth.

-## License
+## Copyright and License

-    Copyright 2013-2016 Eduardo Gurgel <eduardo@gurgel.me>
+Copyright (c) 2013 Eduardo Gurgel <eduardo@gurgel.me>

-    This work is free. You can redistribute it and/or modify it under the
-    terms of the MIT License. See the LICENSE file for more details.
+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.
--- a/lib/httparrot/deny_handler.ex
+++ b/lib/httparrot/deny_handler.ex
@ -18,7 +18,7 @@ defmodule HTTParrot.DenyHandler do
     \  .-"`  `"-.  /
      '.          .'
        '-......-'
-    YOU SHOUDN'T BE HERE
+    YOU SHOULDN'T BE HERE
  """
  def get_plain(req, state) do
    {@body, req, state}
--- a/lib/httparrot/request_store.ex
+++ b/lib/httparrot/request_store.ex
@ -1,6 +1,6 @@
 defmodule HTTParrot.RequestStore do
  @moduledoc """
-  Used to store and retrived requests
+  Used to store and retrieved requests
  """
  @doc """
  Store the requests to the key
@ -26,7 +26,7 @@ defmodule HTTParrot.RequestStore do
  end

  @doc """
-  Clear the saved data on the coresponding key
+  Clear the saved data on the corresponding key
  """
  def clear(key) do
    ConCache.delete(:requests_registry, key)
--- a/lib/httparrot/retrieve_request_handler.ex
+++ b/lib/httparrot/retrieve_request_handler.ex
@ -1,6 +1,6 @@
 defmodule HTTParrot.RetrieveRequestHandler do
  @moduledoc """
-  Retreive saved request and clear the conresponding :id
+  Retrieve saved request and clear the conresponding :id
  """
  use HTTParrot.Cowboy, methods: ~w(GET POST PUT HEAD OPTIONS)

--- a/mix.exs
+++ b/mix.exs
@ -1,19 +1,18 @@
 defmodule Httparrot.Mixfile do
  use Mix.Project

-  @description """
-    HTTP Request & Response Server. An incomplete clone of http://httpbin.org
-  """
+  @source_url "https://github.com/edgurgel/httparrot"
+  @version "1.3.0"

  def project do
    [
      app: :httparrot,
-      version: "1.3.0",
+      version: @version,
      elixir: "~> 1.7",
      name: "HTTParrot",
-      description: @description,
      package: package(),
-      deps: deps()
+      deps: deps(),
+      docs: docs()
    ]
  end

@ -30,20 +29,34 @@ defmodule Httparrot.Mixfile do
      {:exjsx, "~> 3.0 or ~> 4.0"},
      {:con_cache, "~> 0.14.0"},
      {:earmark, "~> 1.0", only: :dev},
-      {:ex_doc, "~> 0.18", only: :dev},
+      {:ex_doc, ">= 0.0.0", only: :dev, runtime: false},
      {:meck, "~> 0.8.13", only: :test}
    ]
  end

  defp package do
    [
+      description: "https://github.com/edgurgel/httparrot",
      maintainers: ["Eduardo Gurgel Pinho"],
      licenses: ["MIT"],
      links: %{
-        "Github" => "https://github.com/edgurgel/httparrot",
+        "Github" => @source_url,
        "HTTParrot" => "http://httparrot.herokuapp.com",
        "httpbin" => "http://httpbin.org"
      }
    ]
  end
+
+  defp docs do
+    [
+      extras: [
+        "LICENSE.md": [title: "License"],
+        "README.md": [title: "Overview"]
+      ],
+      main: "readme",
+      source_url: @source_url,
+      source_ref: "v{@version}",
+      formatters: ["html"]
+    ]
+  end
 end
--- a/mix.lock
+++ b/mix.lock
@ -2,14 +2,16 @@
  "con_cache": {:hex, :con_cache, "0.14.0", "863acb90fa08017be3129074993af944cf7a4b6c3ee7c06c5cd0ed6b94fbc223", [:mix], [], "hexpm", "50887a8949377d0b707a3c6653b7610de06074751b52d0f267f52135f391aece"},
  "cowboy": {:hex, :cowboy, "2.8.0", "f3dc62e35797ecd9ac1b50db74611193c29815401e53bac9a5c0577bd7bc667d", [:rebar3], [{:cowlib, "~> 2.9.1", [hex: :cowlib, repo: "hexpm", optional: false]}, {:ranch, "~> 1.7.1", [hex: :ranch, repo: "hexpm", optional: false]}], "hexpm", "4643e4fba74ac96d4d152c75803de6fad0b3fa5df354c71afdd6cbeeb15fac8a"},
  "cowlib": {:hex, :cowlib, "2.9.1", "61a6c7c50cf07fdd24b2f45b89500bb93b6686579b069a89f88cb211e1125c78", [:rebar3], [], "hexpm", "e4175dc240a70d996156160891e1c62238ede1729e45740bdd38064dad476170"},
-  "earmark": {:hex, :earmark, "1.4.6", "f14260802d8998f30e1654189a0d1699c4aa7d099eb4dad904eb5f41283a70b2", [:mix], [], "hexpm", "c1653a90f63400d029b783a098f4d70a40418ddff14da4cc156a0fee9e72e8d6"},
-  "ex_doc": {:hex, :ex_doc, "0.22.1", "9bb6d51508778193a4ea90fa16eac47f8b67934f33f8271d5e1edec2dc0eee4c", [:mix], [{:earmark, "~> 1.4.0", [hex: :earmark, repo: "hexpm", optional: false]}, {:makeup_elixir, "~> 0.14", [hex: :makeup_elixir, repo: "hexpm", optional: false]}], "hexpm", "d957de1b75cb9f78d3ee17820733dc4460114d8b1e11f7ee4fd6546e69b1db60"},
+  "earmark": {:hex, :earmark, "1.4.15", "2c7f924bf495ec1f65bd144b355d0949a05a254d0ec561740308a54946a67888", [:mix], [{:earmark_parser, ">= 1.4.13", [hex: :earmark_parser, repo: "hexpm", optional: false]}], "hexpm", "3b1209b85bc9f3586f370f7c363f6533788fb4e51db23aa79565875e7f9999ee"},
+  "earmark_parser": {:hex, :earmark_parser, "1.4.15", "b29e8e729f4aa4a00436580dcc2c9c5c51890613457c193cc8525c388ccb2f06", [:mix], [], "hexpm", "044523d6438ea19c1b8ec877ec221b008661d3c27e3b848f4c879f500421ca5c"},
+  "ex_doc": {:hex, :ex_doc, "0.25.1", "4b736fa38dc76488a937e5ef2944f5474f3eff921de771b25371345a8dc810bc", [: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", "3200b0a69ddb2028365281fbef3753ea9e728683863d8cdaa96580925c891f67"},
  "exactor": {:hex, :exactor, "2.2.3", "a6972f43bb6160afeb73e1d8ab45ba604cd0ac8b5244c557093f6e92ce582786", [:mix], [], "hexpm"},
  "exjsx": {:hex, :exjsx, "4.0.0", "60548841e0212df401e38e63c0078ec57b33e7ea49b032c796ccad8cde794b5c", [:mix], [{:jsx, "~> 2.8.0", [hex: :jsx, repo: "hexpm", optional: false]}], "hexpm", "32e95820a97cffea67830e91514a2ad53b888850442d6d395f53a1ac60c82e07"},
  "jsx": {:hex, :jsx, "2.8.3", "a05252d381885240744d955fbe3cf810504eb2567164824e19303ea59eef62cf", [:mix, :rebar3], [], "hexpm", "fc3499fed7a726995aa659143a248534adc754ebd16ccd437cd93b649a95091f"},
-  "makeup": {:hex, :makeup, "1.0.3", "e339e2f766d12e7260e6672dd4047405963c5ec99661abdc432e6ec67d29ef95", [:mix], [{:nimble_parsec, "~> 0.5", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "2e9b4996d11832947731f7608fed7ad2f9443011b3b479ae288011265cdd3dad"},
-  "makeup_elixir": {:hex, :makeup_elixir, "0.14.1", "4f0e96847c63c17841d42c08107405a005a2680eb9c7ccadfd757bd31dabccfb", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "f2438b1a80eaec9ede832b5c41cd4f373b38fd7aa33e3b22d9db79e640cbde11"},
+  "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"},
  "meck": {:hex, :meck, "0.8.13", "ffedb39f99b0b99703b8601c6f17c7f76313ee12de6b646e671e3188401f7866", [:rebar3], [], "hexpm", "d34f013c156db51ad57cc556891b9720e6a1c1df5fe2e15af999c84d6cebeb1a"},
-  "nimble_parsec": {:hex, :nimble_parsec, "0.6.0", "32111b3bf39137144abd7ba1cce0914533b2d16ef35e8abc5ec8be6122944263", [:mix], [], "hexpm", "27eac315a94909d4dc68bc07a4a83e06c8379237c5ea528a9acff4ca1c873c52"},
+  "nimble_parsec": {:hex, :nimble_parsec, "1.1.0", "3a6fca1550363552e54c216debb6a9e95bd8d32348938e13de5eda962c0d7f89", [:mix], [], "hexpm", "08eb32d66b706e913ff748f11694b17981c0b04a33ef470e33e11b3d3ac8f54b"},
  "ranch": {:hex, :ranch, "1.7.1", "6b1fab51b49196860b733a49c07604465a47bdb78aa10c1c16a3d199f7f8c881", [:rebar3], [], "hexpm", "451d8527787df716d99dc36162fca05934915db0b6141bbdac2ea8d3c7afc7d7"},
 }
--- a/test/basic_auth_handler_test.exs
+++ b/test/basic_auth_handler_test.exs
@ -21,7 +21,7 @@ defmodule HTTParrot.BasicAuthHandlerTest do
    assert validate JSX
  end

-  test "is_authorized returns false if user and passwd doesnt match" do
+  test "is_authorized returns false if user and passwd doesn't match" do
    expect(:cowboy_req, :binding, [{[:user, :req1], :user},
                                   {[:passwd, :req1], :passwd}])
    expect(:cowboy_req, :parse_header, [{["authorization", :req1], {:basic, :not_the_user, :passwd}}])
--- a/test/hidden_basic_auth_handler_test.exs
+++ b/test/hidden_basic_auth_handler_test.exs
@ -26,7 +26,7 @@ defmodule HTTParrot.HiddenBasicAuthHandlerTest do
    assert validate(JSX)
  end

-  test "resource_exists returns false if user and passwd doesnt match" do
+  test "resource_exists returns false if user and passwd doesn't match" do
    expect(:cowboy_req, :binding, [{[:user, :req1], :user}, {[:passwd, :req1], :passwd}])

    expect(:cowboy_req, :parse_header, [