Misc doc changes

Besides other documentation changes, this commit ensures the generated HTML doc for HexDocs.pm will become the main source doc for this Elixir library which leverage on latest ExDoc features.
felt · Mar 28, 2021 · d7171c5 · d7171c5
1 parent 6550ac3
commit d7171c5
Show file tree

Hide file tree

Showing 7 changed files with 84 additions and 54 deletions.
diff --git a/.formatter.exs 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
@@ -1,14 +1,14 @@
 # The directory Mix will write compiled artifacts to.
-/_build
+/_build/
 
 # If you run "mix test --cover", coverage assets end up here.
-/cover
+/cover/
 
 # The directory Mix downloads your dependencies sources to.
-/deps
+/deps/
 
 # Where 3rd-party dependencies like ExDoc output generated docs.
-/doc
+/doc/
 
 # Ignore .fetch files in case you like to edit your project deps locally.
 /.fetch
@@ -19,7 +19,11 @@ erl_crash.dump
 # Also ignore archive artifacts (built via "mix archive.build").
 *.ez
 
-/.elixir_ls
+# Ignore package tarball (built via "mix hex.build").
+geo_postgis-*.tar
+
+# Temporary files for e.g. tests.
+/tmp/
 
 # Emacs project file
 .projectile
diff --git a/README.md b/README.md
@@ -1,20 +1,24 @@
 # GeoPostGIS
 
 [![Build Status](https://travis-ci.org/bryanjos/geo_postgis.svg?branch=master)](https://travis-ci.org/bryanjos/geo_postgis)
-[![Hex.pm](https://img.shields.io/hexpm/v/geo_postgis.svg)](https://hex.pm/packages/geo_postgis)
+[![Module Version](https://img.shields.io/hexpm/v/geo_postgis.svg)](https://hex.pm/packages/geo_postgis)
+[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/geo_postgis/)
+[![Total Download](https://img.shields.io/hexpm/dt/geo_postgis.svg)](https://hex.pm/packages/geo_postgis)
+[![License](https://img.shields.io/hexpm/l/geo_postgis.svg)](https://github.com/bryanjos/geo_postgis/blob/master/LICENSE)
+[![Last Updated](https://img.shields.io/github/last-commit/bryanjos/geo_postgis.svg)](https://github.com/bryanjos/geo_postgis/commits/master)
 
 Postgrex extension for the PostGIS data types. Uses the [geo](https://github.com/bryanjos/geo) library
 
-[Documentation](http://hexdocs.pm/geo_postgis)
-
 ## Installation
 
-If [available in Hex](https://hex.pm/docs/publish), the package can be installed
-by adding `geo_postgis` to your list of dependencies in `mix.exs`:
+The package can be installed by adding `:geo_postgis` to your list of
+dependencies in `mix.exs`:
 
 ```elixir
 def deps do
-  [{:geo_postgis, "~> 3.1"}]
+  [
+    {:geo_postgis, "~> 3.1"}
+  ]
 end
 ```
 
@@ -23,7 +27,11 @@ Make sure PostGIS extension to your database is installed. More information [her
 ### Optional Configuration
 
 ```elixir
-# When a binary is passed to `Geo.PostGIS.Geometry.cast/1` implementation of `Ecto.Type.cast/1`, it is assumed to be a GeoJSON string. When this happens, geo_postgis will use Poison, by default, to convert the binary to a map and then convert that map to one of the Geo structs. If in these cases you would like to use a different JSON parser, you can set the config below.
+# When a binary is passed to `Geo.PostGIS.Geometry.cast/1` implementation of
+# `Ecto.Type.cast/1`, it is assumed to be a GeoJSON string. When this happens,
+# geo_postgis will use Poison, by default, to convert the binary to a map and
+# then convert that map to one of the Geo structs. If in these cases you would
+# like to use a different JSON parser, you can set the config below.
 
 # config.exs
 config :geo_postgis,
@@ -32,7 +40,7 @@ config :geo_postgis,
 
 ## Examples
 
-### Postgrex Extension for the PostGIS data types, Geometry and Geography
+Postgrex Extension for the PostGIS data types, Geometry and Geography:
 
 ```elixir
 Postgrex.Types.define(MyApp.PostgresTypes, [Geo.PostGIS.Extension], [])
@@ -57,7 +65,7 @@ Postgrex.Connection.query(pid, "SELECT * FROM point_test")
 rows: [{42, %Geo.Point{coordinates: {30.0, -90.0}, srid: 4326 }}]}}
 ```
 
-### Use with Ecto Referencing [the documentation](https://hexdocs.pm/ecto_sql/Ecto.Adapters.Postgres.html#module-extensions):
+Use with [Ecto](https://hexdocs.pm/ecto_sql/Ecto.Adapters.Postgres.html#module-extensions):
 
 ```elixir
 #If using with Ecto, you may want something like thing instead
@@ -102,7 +110,7 @@ defmodule Repo.Migrations.Init do
 end
 ```
 
-### Ecto migrations can also use more elaborate [Postgis GIS Objects](http://postgis.net/docs/using_postgis_dbmanagement.html#RefObject). These types are useful for enforcing constraints on {Lng,Lat} (order matters), or ensuring that a particular projection/coordinate system/format is used.
+Ecto migrations can also use more elaborate [PostGIS GIS Objects](http://postgis.net/docs/using_postgis_dbmanagement.html#RefObject). These types are useful for enforcing constraints on `{Lng,Lat}` (order matters), or ensuring that a particular projection/coordinate system/format is used.
 
 ```elixir
 defmodule Repo.Migrations.AdvancedInit do
@@ -127,7 +135,7 @@ defmodule Repo.Migrations.AdvancedInit do
 end
 ```
 
-Be sure to enable the Postgis extension if you haven't already done so:
+Be sure to enable the PostGIS extension if you haven't already done so:
 
 ```elixir
 defmodule MyApp.Repo.Migrations.EnablePostgis do
@@ -143,7 +151,7 @@ defmodule MyApp.Repo.Migrations.EnablePostgis do
 end
 ```
 
-### [Postgis functions](http://postgis.net/docs/manual-1.3/ch06.html) can also be used in ecto queries. Currently only the OpenGIS functions are implemented. Have a look at [lib/geo_postgis.ex](lib/geo_postgis.ex) for the implemented functions. You can use them like:
+[PostGIS functions](http://postgis.net/docs/manual-1.3/ch06.html) can also be used in Ecto queries. Currently only the OpenGIS functions are implemented. Have a look at [lib/geo_postgis.ex](lib/geo_postgis.ex) for the implemented functions. You can use them like:
 
 ```elixir
 defmodule Example do
@@ -155,7 +163,6 @@ defmodule Example do
     query
     |> Repo.one
   end
-
 end
 ```
 
@@ -168,3 +175,10 @@ After you got the dependencies via `mix deps.get` make sure that:
 * your `postgres` db user can login without a password or you set the `PGPASSWORD` environment variable appropriately
 
 Then you can run the tests as you are used to with `mix test`.
+
+
+## Copyright and License
+
+Copyright (c) 2017 Bryan Joseph
+
+Released under the MIT License, which can be found in the repository in [`LICENSE`](https://github.com/bryanjos/geo_postgis/blob/master/LICENSE).
diff --git a/lib/geo_postgis.ex b/lib/geo_postgis.ex
@@ -1,20 +1,21 @@
 defmodule Geo.PostGIS do
   @moduledoc """
-    Postgis functions that can used in ecto queries
-    [PostGIS Function Documentation](http://postgis.net/docs/manual-1.3/ch06.html)
+  PostGIS functions that can used in ecto queries
+  [PostGIS Function Documentation](http://postgis.net/docs/manual-1.3/ch06.html).
 
-    Currently only the OpenGIS functions are implemented
+  Currently only the OpenGIS functions are implemented.
+
+  ## Examples
 
-    ex.
       defmodule Example do
         import Ecto.Query
         import Geo.PostGIS
 
         def example_query(geom) do
           from location in Location, limit: 5, select: st_distance(location.geom, ^geom)
         end
-
       end
+
   """
 
   defmacro st_transform(wkt, srid) do
@@ -24,9 +25,9 @@ defmodule Geo.PostGIS do
   defmacro st_distance(geometryA, geometryB) do
     quote do: fragment("ST_Distance(?,?)", unquote(geometryA), unquote(geometryB))
   end
-   
+
   @doc """
-  Casts the 2 geometries given to geographies in order to return distance in meters
+  Casts the 2 geometries given to geographies in order to return distance in meters.
   """
   defmacro st_distance_in_meters(geometryA, geometryB) do
     quote do:
@@ -56,7 +57,7 @@ defmodule Geo.PostGIS do
   end
 
   @doc """
-  Casts the 2 geometries given to geographies in order to check for distance in meters
+  Casts the 2 geometries given to geographies in order to check for distance in meters.
   """
   defmacro st_dwithin_in_meters(geometryA, geometryB, float) do
     quote do:
@@ -382,7 +383,7 @@ defmodule Geo.PostGIS do
     quote do: fragment("ST_BdMPolyFromText(?, ?)", unquote(wkt), unquote(srid))
   end
 
-  defmacro st_flip_coordinates(geometryA) do 
+  defmacro st_flip_coordinates(geometryA) do
     quote do: fragment("ST_FlipCoordinates(?)", unquote(geometryA))
   end
 end
diff --git a/lib/geo_postgis/extension.ex b/lib/geo_postgis/extension.ex
@@ -1,13 +1,15 @@
 defmodule Geo.PostGIS.Extension do
-  @behaviour Postgrex.Extension
-
   @moduledoc """
-  PostGIS extension for Postgrex. Supports Geometry and Geography data types
+  PostGIS extension for Postgrex. Supports Geometry and Geography data types.
+
+  ## Examples
+
+  Create a new Postgrex Types module:
 
-      #Create a new Postgrex Types module:
       Postgrex.Types.define(MyApp.PostgresTypes, [Geo.PostGIS.Extension], [])
 
-      #If using with Ecto, you may want something like thing instead
+  If using with Ecto, you may want something like thing instead:
+
       Postgrex.Types.define(MyApp.PostgresTypes,
                     [Geo.PostGIS.Extension] ++ Ecto.Adapters.Postgres.extensions(),
                     json: Poison)
@@ -36,6 +38,8 @@ defmodule Geo.PostGIS.Extension do
 
   """
 
+  @behaviour Postgrex.Extension
+
   @geo_types [
     Geo.GeometryCollection,
     Geo.LineString,

diff --git a/mix.exs b/mix.exs
@@ -1,57 +1,58 @@
 defmodule GeoPostgis.Mixfile do
   use Mix.Project
 
+  @source_url "https://github.com/bryanjos/geo_postgis"
+  @version "3.3.1"
+
   def project do
     [
       app: :geo_postgis,
-      version: "3.3.1",
+      version: @version,
       elixir: "~> 1.7",
-      build_embedded: Mix.env() == :prod,
       start_permanent: Mix.env() == :prod,
+      name: "GeoPostGIS",
       deps: deps(),
-      description: description(),
       package: package(),
-      name: "GeoPostGIS",
+      docs: docs(),
       elixirc_paths: elixirc_paths(Mix.env()),
-      source_url: source_url()
     ]
   end
 
   def application do
     [extra_applications: [:logger]]
   end
 
-  defp source_url do
-    "https://github.com/bryanjos/geo_postgis"
-  end
-
   defp elixirc_paths(:test), do: ["lib", "test/support"]
   defp elixirc_paths(_), do: ["lib"]
 
-  defp description do
-    """
-    PostGIS extension for Postgrex.
-    """
-  end
-
   defp deps do
     [
       {:geo, "~> 3.3"},
       {:postgrex, "~> 0.14"},
-      {:ex_doc, "~> 0.21.0", only: :dev},
+      {:ex_doc, ">= 0.0.0", only: :dev, runtime: false},
       {:ecto_sql, "~> 3.0", optional: true, only: :test},
       {:poison, "~> 2.2 or ~> 3.0 or ~> 4.0", optional: true},
       {:jason, "~> 1.0", optional: true}
     ]
   end
 
   defp package do
-    # These are the default files included in the package
     [
+      description: "PostGIS extension for Postgrex.",
       files: ["lib", "mix.exs", "README.md", "CHANGELOG.md"],
       maintainers: ["Bryan Joseph"],
       licenses: ["MIT"],
-      links: %{"GitHub" => source_url()}
+      links: %{"GitHub" => @source_url}
+    ]
+  end
+
+  defp docs do
+    [
+      extras: ["CHANGELOG.md", "README.md"],
+      main: "readme",
+      source_url: @source_url,
+      source_ref: "v#{@version}",
+      formatters: ["html"]
     ]
   end
 end
diff --git a/mix.lock b/mix.lock
@@ -3,14 +3,16 @@
   "db_connection": {:hex, :db_connection, "2.2.0", "e923e88887cd60f9891fd324ac5e0290954511d090553c415fbf54be4c57ee63", [:mix], [{:connection, "~> 1.0.2", [hex: :connection, repo: "hexpm", optional: false]}], "hexpm", "bdf196feedfa6b83071e808b2b086fb113f8a1c4c7761f6eff6fe4b96aba0086"},
   "decimal": {:hex, :decimal, "1.8.0", "ca462e0d885f09a1c5a342dbd7c1dcf27ea63548c65a65e67334f4b61803822e", [:mix], [], "hexpm", "52694ef56e60108e5012f8af9673874c66ed58ac1c4fae9b5b7ded31786663f5"},
   "earmark": {:hex, :earmark, "1.4.3", "364ca2e9710f6bff494117dbbd53880d84bebb692dafc3a78eb50aa3183f2bfd", [:mix], [], "hexpm", "8cf8a291ebf1c7b9539e3cddb19e9cef066c2441b1640f13c34c1d3cfc825fec"},
+  "earmark_parser": {:hex, :earmark_parser, "1.4.12", "b245e875ec0a311a342320da0551da407d9d2b65d98f7a9597ae078615af3449", [:mix], [], "hexpm", "711e2cc4d64abb7d566d43f54b78f7dc129308a63bc103fbd88550d2174b3160"},
   "ecto": {:hex, :ecto, "3.3.0", "9193e261d25c1814324d0b3304fccbadab840b286d270c3b75dfd28c30a3ae15", [:mix], [{:decimal, "~> 1.6", [hex: :decimal, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: true]}], "hexpm", "f50c944ea0de690510ed90b266c4ff55a6f15ce09b891d77681861ce2f150484"},
   "ecto_sql": {:hex, :ecto_sql, "3.3.0", "6023515613a28541af9d163fda047f67747b75b23a00d7d8bf5009d46a6ee4d0", [:mix], [{:db_connection, "~> 2.2", [hex: :db_connection, repo: "hexpm", optional: false]}, {:ecto, "~> 3.3", [hex: :ecto, repo: "hexpm", optional: false]}, {:myxql, "~> 0.3.0", [hex: :myxql, repo: "hexpm", optional: true]}, {:postgrex, "~> 0.15.0", [hex: :postgrex, repo: "hexpm", optional: true]}, {:telemetry, "~> 0.4.0", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm", "cddbff19dd6ac5c786259efa1429269687ffd8299b235f039d4a11e0706f6e40"},
-  "ex_doc": {:hex, :ex_doc, "0.21.3", "857ec876b35a587c5d9148a2512e952e24c24345552259464b98bfbb883c7b42", [:mix], [{:earmark, "~> 1.4", [hex: :earmark, repo: "hexpm", optional: false]}, {:makeup_elixir, "~> 0.14", [hex: :makeup_elixir, repo: "hexpm", optional: false]}], "hexpm", "0db1ee8d1547ab4877c5b5dffc6604ef9454e189928d5ba8967d4a58a801f161"},
+  "ex_doc": {:hex, :ex_doc, "0.24.1", "15673de99154f93ca7f05900e4e4155ced1ee0cd34e0caeee567900a616871a4", [: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", "07972f17bdf7dc7b5bd76ec97b556b26178ed3f056e7ec9288eb7cea7f91cce2"},
   "geo": {:hex, :geo, "3.3.3", "1119302b20d21515fbcec0a180b82653524067873ed333e7fa1f55e39959d702", [:mix], [], "hexpm", "8297ae0ac5ce47bb608b2bc8a63030460020ae537de9464a7a652f25baf6d2c1"},
   "jason": {:hex, :jason, "1.1.2", "b03dedea67a99223a2eaf9f1264ce37154564de899fd3d8b9a21b1a6fd64afe7", [:mix], [{:decimal, "~> 1.0", [hex: :decimal, repo: "hexpm", optional: true]}], "hexpm", "fdf843bca858203ae1de16da2ee206f53416bbda5dc8c9e78f43243de4bc3afe"},
-  "makeup": {:hex, :makeup, "1.0.0", "671df94cf5a594b739ce03b0d0316aa64312cee2574b6a44becb83cd90fb05dc", [:mix], [{:nimble_parsec, "~> 0.5.0", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "a10c6eb62cca416019663129699769f0c2ccf39428b3bb3c0cb38c718a0c186d"},
-  "makeup_elixir": {:hex, :makeup_elixir, "0.14.0", "cf8b7c66ad1cff4c14679698d532f0b5d45a3968ffbcbfd590339cb57742f1ae", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "d4b316c7222a85bbaa2fd7c6e90e37e953257ad196dc229505137c5e505e9eff"},
-  "nimble_parsec": {:hex, :nimble_parsec, "0.5.3", "def21c10a9ed70ce22754fdeea0810dafd53c2db3219a0cd54cf5526377af1c6", [:mix], [], "hexpm", "589b5af56f4afca65217a1f3eb3fee7e79b09c40c742fddc1c312b3ac0b3399f"},
+  "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"},
+  "nimble_parsec": {:hex, :nimble_parsec, "1.1.0", "3a6fca1550363552e54c216debb6a9e95bd8d32348938e13de5eda962c0d7f89", [:mix], [], "hexpm", "08eb32d66b706e913ff748f11694b17981c0b04a33ef470e33e11b3d3ac8f54b"},
   "poison": {:hex, :poison, "4.0.1", "bcb755a16fac91cad79bfe9fc3585bb07b9331e50cfe3420a24bcc2d735709ae", [:mix], [], "hexpm", "ba8836feea4b394bb718a161fc59a288fe0109b5006d6bdf97b6badfcf6f0f25"},
   "postgrex": {:hex, :postgrex, "0.15.3", "5806baa8a19a68c4d07c7a624ccdb9b57e89cbc573f1b98099e3741214746ae4", [:mix], [{:connection, "~> 1.0", [hex: :connection, repo: "hexpm", optional: false]}, {:db_connection, "~> 2.1", [hex: :db_connection, repo: "hexpm", optional: false]}, {:decimal, "~> 1.5", [hex: :decimal, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: true]}], "hexpm", "4737ce62a31747b4c63c12b20c62307e51bb4fcd730ca0c32c280991e0606c90"},
   "telemetry": {:hex, :telemetry, "0.4.1", "ae2718484892448a24470e6aa341bc847c3277bfb8d4e9289f7474d752c09c7f", [:rebar3], [], "hexpm", "4738382e36a0a9a2b6e25d67c960e40e1a2c95560b9f936d8e29de8cd858480f"},