From e268db592498685af701498133fb667e1e841d05 Mon Sep 17 00:00:00 2001 From: "Kian-Meng, Ang" Date: Tue, 7 Sep 2021 06:39:19 +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 | 3 +- .gitignore | 23 ++++++++----- .travis.yml | 0 LICENSE => LICENSE.md | 2 +- README.md | 21 +++++++++--- bench/envelope_bench.exs | 0 bench/envelope_compare_bench.exs | 0 bench/shapes/cities.json | 0 bench/shapes/counties.json | 0 bench/shapes/interstates.json | 0 bench/shapes/states.json | 0 config/config.exs | 0 lib/envelope.ex | 59 ++++++++++++++++++++++++++------ mix.exs | 49 ++++++++++++++++---------- mix.lock | 4 +-- test/envelope_test.exs | 0 test/test_helper.exs | 0 17 files changed, 115 insertions(+), 46 deletions(-) mode change 100755 => 100644 .gitignore mode change 100755 => 100644 .travis.yml rename LICENSE => LICENSE.md (98%) mode change 100755 => 100644 mode change 100755 => 100644 README.md mode change 100755 => 100644 bench/envelope_bench.exs mode change 100755 => 100644 bench/envelope_compare_bench.exs mode change 100755 => 100644 bench/shapes/cities.json mode change 100755 => 100644 bench/shapes/counties.json mode change 100755 => 100644 bench/shapes/interstates.json mode change 100755 => 100644 bench/shapes/states.json mode change 100755 => 100644 config/config.exs mode change 100755 => 100644 lib/envelope.ex mode change 100755 => 100644 mix.exs mode change 100755 => 100644 mix.lock mode change 100755 => 100644 test/envelope_test.exs mode change 100755 => 100644 test/test_helper.exs diff --git a/.formatter.exs b/.formatter.exs index 2bed17c..d2cda26 100644 --- a/.formatter.exs +++ b/.formatter.exs @@ -1,3 +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 old mode 100755 new mode 100644 index 0a380d8..b620e25 --- a/.gitignore +++ b/.gitignore @@ -1,14 +1,17 @@ # 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 +# 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 @@ -16,8 +19,12 @@ erl_crash.dump # Also ignore archive artifacts (built via "mix archive.build"). *.ez -.elixir_ls +# Ignore package tarball (built via "mix hex.build"). +envelope-*.tar -.DS_Store +# Temporary files, for example, from tests. +/tmp/ -tags +# Misc. +.DS_Store +.elixir_ls/ diff --git a/.travis.yml b/.travis.yml old mode 100755 new mode 100644 diff --git a/LICENSE b/LICENSE.md old mode 100755 new mode 100644 similarity index 98% rename from LICENSE rename to LICENSE.md index 8087257..411ddfc --- a/LICENSE +++ b/LICENSE.md @@ -1,4 +1,4 @@ -MIT License +# MIT License Copyright (c) 2017 Powell Kinney diff --git a/README.md b/README.md old mode 100755 new mode 100644 index 564986b..ce315ee --- a/README.md +++ b/README.md @@ -1,7 +1,11 @@ # Envelope [![CI](https://github.com/pkinney/envelope_ex/actions/workflows/ci.yaml/badge.svg)](https://github.com/pkinney/envelope_ex/actions/workflows/ci.yaml) -[![Hex.pm](https://img.shields.io/hexpm/v/envelope.svg)](https://hex.pm/packages/envelope) +[![Hex Version](https://img.shields.io/hexpm/v/envelope.svg)](https://hex.pm/packages/envelope) +[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/envelope/) +[![Total Download](https://img.shields.io/hexpm/dt/envelope.svg)](https://hex.pm/packages/envelope) +[![License](https://img.shields.io/hexpm/l/envelope.svg)](https://github.com/pkinney/envelope_ex/blob/master/LICENSE.md) +[![Last Updated](https://img.shields.io/github/last-commit/pkinney/envelope_ex.svg)](https://github.com/pkinney/envelope_ex/commits/master) A library for calculating envelopes (axis-aligned bounding boxes) of geometries and tools to compare them. This is most useful as an approximation of spacial relationships between more @@ -11,7 +15,9 @@ complicated geometries. ```elixir defp deps do - [{:envelope, "~> 1.3"}] + [ + {:envelope, "~> 1.3"} + ] end ``` @@ -52,7 +58,7 @@ Envelope.contains?( # => false ``` -## Applicaiton +## Application In the context of a larger Geometry/GIS application, Envelopes can be used to drastically decrease processing overhead for comparing two geometries that are @@ -88,8 +94,15 @@ def intersect?(poly1, poly2) do end ``` -or more concisely +or more concisely: ```elixir Envelope.intersects?(Envelope.from_geo(poly1), Envelope.from_geo(poly2)) && Topo.intersects?(poly1, poly2) ``` + +## Copyright and License + +Copyright (c) 2017 Powell Kinney + +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/bench/envelope_bench.exs b/bench/envelope_bench.exs old mode 100755 new mode 100644 diff --git a/bench/envelope_compare_bench.exs b/bench/envelope_compare_bench.exs old mode 100755 new mode 100644 diff --git a/bench/shapes/cities.json b/bench/shapes/cities.json old mode 100755 new mode 100644 diff --git a/bench/shapes/counties.json b/bench/shapes/counties.json old mode 100755 new mode 100644 diff --git a/bench/shapes/interstates.json b/bench/shapes/interstates.json old mode 100755 new mode 100644 diff --git a/bench/shapes/states.json b/bench/shapes/states.json old mode 100755 new mode 100644 diff --git a/config/config.exs b/config/config.exs old mode 100755 new mode 100644 diff --git a/lib/envelope.ex b/lib/envelope.ex old mode 100755 new mode 100644 index 4d79a79..f5288e2 --- a/lib/envelope.ex +++ b/lib/envelope.ex @@ -1,6 +1,7 @@ defmodule Envelope do @moduledoc ~S""" A library for calculating envelopes of geometries and tools to compare them. + This is most useful as an approximation of spacial relationships between more complicated geometries. @@ -10,12 +11,13 @@ defmodule Envelope do iex> Envelope.from_geo( %Geo.LineString{coordinates: [{1, 3}, {2, -1}, {0, -1}, {1, 3}]} ) %Envelope{ min_x: 0, min_y: -1, max_x: 2, max_y: 3 } - You can also expand an existing Envelope with a geometry or another Envelope + You can also expand an existing Envelope with a geometry or another Envelope: iex> a = Envelope.from_geo( %Geo.Polygon{coordinates: [[{2, -2}, {20, -2}, {11, 11}, {2, -2}]]} ) ...> b = %Geo.LineString{coordinates: [{1, 3}, {2, -1}, {0, -1}, {1, 3}]} ...> Envelope.expand(a, b) %Envelope{ min_x: 0, min_y: -2, max_x: 20, max_y: 11 } + """ defstruct min_x: 0, min_y: 0, max_x: 0, max_y: 0 @@ -45,6 +47,7 @@ defmodule Envelope do coordinates. ## Examples + iex> Envelope.from_geo %{coordinates: [{11, 10}, {4, 2.5}, {16, 2.5}, {11, 10}]} %Envelope{ max_x: 16, max_y: 10, min_x: 4, min_y: 2.5 } @@ -56,6 +59,7 @@ defmodule Envelope do iex> Envelope.from_geo {1, 3} %Envelope{ min_x: 1, min_y: 3, max_x: 1, max_y: 3 } + """ @spec from_geo(points()) :: t() def from_geo({x, y}) when is_number(x) and is_number(y), @@ -86,6 +90,7 @@ defmodule Envelope do - `Geo.Polygon` will be returned when an envelope has non-zeron area ## Examples + iex> Envelope.to_geo %Envelope{ max_x: 16, max_y: 10, min_x: 4, min_y: 2.5 } %Geo.Polygon{coordinates: [[{4, 2.5}, {4, 10}, {16, 10}, {16, 2.5}, {4, 2.5}]]} @@ -97,6 +102,7 @@ defmodule Envelope do iex> Envelope.to_geo %Envelope{ min_x: 1, min_y: 3, max_x: 1, max_y: 3 } %Geo.Point{coordinates: {1, 3}} + """ @spec to_geo(t()) :: %Geo.Polygon{} | %Geo.Point{} | %Geo.LineString{} def to_geo(%Envelope{min_x: x, min_y: y, max_x: x, max_y: y}), @@ -122,34 +128,40 @@ defmodule Envelope do } @doc ~S""" - Returns an `Envelope` that represents no extent at all. This is primarily - a convenience function for starting an expanding Envelope. Internally, - "empty" Envelopes are represented with `nil` values for all extents. + Returns an `Envelope` that represents no extent at all. + + This is primarily a convenience function for starting an expanding Envelope. + Internally, "empty" Envelopes are represented with `nil` values for all + extents. Note that there is a important distinction between an empty Envelope and an Envelope around a single Point (where the min and max for each axis are real numbers but may represent zero area). ## Examples + iex> Envelope.empty %Envelope{max_x: nil, max_y: nil, min_x: nil, min_y: nil} iex> Envelope.empty |> Envelope.empty? true + """ @spec empty() :: t() def empty, do: %Envelope{min_x: nil, min_y: nil, max_x: nil, max_y: nil} @doc ~S""" Returns `true` if the given envelope is empty (has non-existent extent), - otherwise `false` + otherwise `false`. ## Examples + iex> Envelope.empty |> Envelope.empty? true iex> %Envelope{ min_x: 0, min_y: -1, max_x: 2, max_y: 3 } |> Envelope.empty? false + """ @spec empty?(t()) :: boolean() def empty?(%Envelope{min_x: nil, min_y: nil, max_x: nil, max_y: nil}), do: true @@ -159,6 +171,7 @@ defmodule Envelope do Returns a new Envelope that is expanded to include an additional geometry. ## Examples + iex> a = Envelope.from_geo(%Geo.Polygon{coordinates: [[{2, -2}, {20, -2}, {11, 11}, {2, -2}]]}) ...> b = %Geo.LineString{coordinates: [{1, 3}, {2, -1}, {0, -1}, {1, 3}]} ...> Envelope.expand(a, b) @@ -177,6 +190,7 @@ defmodule Envelope do iex> Envelope.expand(Envelope.empty, Envelope.empty) |> Envelope.empty? true + """ @spec expand(t(), point() | t() | points()) :: t() def expand(%Envelope{} = env1, %Envelope{} = env2) do @@ -204,11 +218,13 @@ defmodule Envelope do in each axis by `radius`. ## Examples + iex> Envelope.expand_by(Envelope.from_geo(%Geo.Polygon{coordinates: [[{2, -2}, {20, -2}, {11, 11}, {2, -2}]]}), 3) %Envelope{ min_x: -1, min_y: -5, max_x: 23, max_y: 14 } iex> Envelope.expand_by(Envelope.empty, 4) |> Envelope.empty? true + """ @spec expand_by(t(), number()) :: t() def expand_by(%Envelope{} = env, radius) when is_number(radius) and radius >= 0 do @@ -230,8 +246,10 @@ defmodule Envelope do Simple distance from the left bounadary to the right boundary of the Envelope. ## Examples + iex> Envelope.width(Envelope.from_geo(%Geo.Polygon{coordinates: [[{2, -2}, {20, -2}, {11, 11}, {2, -2}]]})) 18 + """ @spec width(t()) :: number() def width(%Envelope{} = env) do @@ -239,12 +257,15 @@ defmodule Envelope do end @doc ~S""" - When an Envelope's coordinates are in degress of longitude and latitude, calculates the - great circle distance between the center of the east and west extent in meters. + When an Envelope's coordinates are in degrees of longitude and latitude, + calculates the great circle distance between the center of the east and west + extent in meters. ## Examples + iex> Envelope.width_gc(Envelope.from_geo(%Geo.Polygon{coordinates: [[{2, -2}, {20, -2}, {11, 11}, {2, -2}]]})) |> round 1982362 + """ @spec width_gc(t()) :: number() def width_gc(%Envelope{} = env) do @@ -255,11 +276,13 @@ defmodule Envelope do end @doc ~S""" - Simple distance from the bottom bounadary to the top boundary of the Envelope. + Simple distance from the bottom boundary to the top boundary of the Envelope. ## Examples + iex> Envelope.height(Envelope.from_geo(%Geo.Polygon{coordinates: [[{2, -2}, {20, -2}, {11, 11}, {2, -2}]]})) 13 + """ @spec height(t()) :: number() def height(%Envelope{} = env) do @@ -267,12 +290,15 @@ defmodule Envelope do end @doc ~S""" - When an Envelope's coordinates are in degress of longitude and latitude, calculates the - great circle distance between the center of the north and south extent in meters. + When an Envelope's coordinates are in degrees of longitude and latitude, + calculates the great circle distance between the center of the north and + south extent in meters. ## Examples + iex> Envelope.height_gc(Envelope.from_geo(%Geo.Polygon{coordinates: [[{2, -2}, {20, -2}, {11, 11}, {2, -2}]]})) |> round 1445536 + """ @spec height_gc(t()) :: number() def height_gc(%Envelope{} = env) do @@ -283,8 +309,10 @@ defmodule Envelope do Calculates the simple area of an Envelope. ## Examples + iex> Envelope.area(Envelope.from_geo(%Geo.Polygon{coordinates: [[{2, -2}, {20, -2}, {11, 11}, {2, -2}]]})) 234 + """ @spec area(t()) :: number() def area(%Envelope{} = env) do @@ -292,11 +320,14 @@ defmodule Envelope do end @doc ~S""" - Estimates the area of an Envelope in square meters when the Envelope's coordinates are in degress of longitude and latitude. + Estimates the area of an Envelope in square meters when the Envelope's + coordinates are in degrees of longitude and latitude. ## Examples + iex> Envelope.area_gc(Envelope.from_geo(%Geo.Polygon{coordinates: [[{2, -2}, {20, -2}, {11, 11}, {2, -2}]]})) |> round 2865575088701 + """ @spec area_gc(t()) :: number() def area_gc(%Envelope{} = env) do @@ -326,6 +357,7 @@ defmodule Envelope do Returns whether one envelope fully contains another envelope or point. ## Examples + iex> Envelope.contains?( ...> %Envelope{ min_x: -1, min_y: -5, max_x: 23, max_y: 14 }, ...> %Envelope{ min_x: 0, min_y: 3, max_x: 7, max_y: 4 }) @@ -340,6 +372,7 @@ defmodule Envelope do ...> %Geo.Polygon{ coordinates: [{-1, 3}, {-3, -1}, { 5, -3}, {4, 12}, {-2, 11}, {-1, 3}] }, ...> {0, 11}) true + """ @spec contains?(t() | points(), t() | points()) :: boolean() def contains?(%Envelope{} = env, {x, y}) do @@ -360,6 +393,7 @@ defmodule Envelope do The inverse of the relationship tested by Envelope#contains? ## Examples + iex> Envelope.within?( ...> %Envelope{ min_x: 0, min_y: 3, max_x: 7, max_y: 4 }, ...> %Envelope{ min_x: -1, min_y: -5, max_x: 23, max_y: 14 }) @@ -369,6 +403,7 @@ defmodule Envelope do ...> %Geo.Polygon{ coordinates: [{-1, 3}, {-3, -1}, { 5, -3}, {4, 12}, {-2, 11}, {-1, 3}] }, ...> {0, 11}) false + """ @spec within?(t() | points(), t() | points()) :: boolean() def within?(a, b), do: contains?(b, a) @@ -377,6 +412,7 @@ defmodule Envelope do Returns whether two envelopes touch or intersect. ## Examples + iex> Envelope.intersects?( ...> %Envelope{ min_x: -1, min_y: -5, max_x: 23, max_y: 14 }, ...> %Envelope{ min_x: 0, min_y: 3, max_x: 7, max_y: 4 }) @@ -386,6 +422,7 @@ defmodule Envelope do ...> %Envelope{ min_x: -1, min_y: 5, max_x: 23, max_y: 14 }, ...> %Envelope{ min_x: 0, min_y: -3, max_x: 7, max_y: 4 }) false + """ @spec intersects?(t() | points(), t() | points()) :: boolean() def intersects?(%Envelope{} = env1, %Envelope{} = env2) do diff --git a/mix.exs b/mix.exs old mode 100755 new mode 100644 index 33b6be5..d7db09e --- a/mix.exs +++ b/mix.exs @@ -1,58 +1,56 @@ defmodule Envelope.Mixfile do use Mix.Project - def project() do + @source_url "https://github.com/pkinney/envelope_ex" + @version "1.3.1" + + def project do [ app: :envelope, - version: "1.3.1", + version: @version, elixir: "~> 1.2", - description: description(), - package: package(), build_embedded: Mix.env() == :prod, start_permanent: Mix.env() == :prod, test_coverage: [tool: ExCoveralls], preferred_cli_env: [coveralls: :test], + aliases: aliases(), deps: deps(), - aliases: aliases() + docs: docs(), + package: package() ] end - def application() do + def application do [applications: [:logger, :geo, :distance]] end - defp deps() do + defp deps do [ {:geo, "~> 1.0 or ~> 2.0 or ~> 3.0"}, {:distance, "~> 0.2.1 or ~> 1.0"}, {:excoveralls, "~> 0.4", only: :test}, - {:earmark, "~> 1.0", only: :dev}, - {:ex_doc, "~> 0.24", only: :dev, runtime: false}, + {:ex_doc, ">= 0.0.0", only: :dev, runtime: false}, {:poison, "~> 3.0", only: [:dev, :test]}, {:credo, "~> 0.8", only: [:dev, :test], runtime: false}, {:dialyxir, "~> 0.4", only: [:dev], runtime: false} ] end - defp description do - """ - A library for calculating envelopes of geometries and tools to compare them. - """ - end - - defp package() do + defp package do [ + description: + "A library for calculating envelopes of geometries " <> + "and tools to compare them.", files: ["lib/envelope.ex", "mix.exs", "README*"], maintainers: ["Powell Kinney"], licenses: ["MIT"], links: %{ - "GitHub" => "https://github.com/pkinney/envelope_ex", - "Docs" => "https://hexdocs.pm/envelope/Envelope.html" + "GitHub" => @source_url } ] end - defp aliases() do + defp aliases do [ validate: [ "clean", @@ -63,4 +61,17 @@ defmodule Envelope.Mixfile do ] ] end + + defp docs do + [ + extras: [ + "LICENSE.md": [title: "License"], + "README.md": [title: "Overview"] + ], + main: "readme", + source_url: @source_url, + source_ref: "master", + formatters: ["html"] + ] + end end diff --git a/mix.lock b/mix.lock old mode 100755 new mode 100644 index 25fc9ec..81c839e --- a/mix.lock +++ b/mix.lock @@ -6,8 +6,8 @@ "dialyxir": {:hex, :dialyxir, "0.5.1", "b331b091720fd93e878137add264bac4f644e1ddae07a70bf7062c7862c4b952", [:mix], [], "hexpm", "6c32a70ed5d452c6650916555b1f96c79af5fc4bf286997f8b15f213de786f73"}, "distance": {:hex, :distance, "1.0.0", "b2d6ed09057e110bb275263cbcc6804ebc0a704cbe79d3a94fa68860e34bb38f", [:mix], [{:seg_seg, "~> 0.1", [hex: :seg_seg, repo: "hexpm", optional: false]}], "hexpm", "7978d58d8a1032aed2ccf2f30e517d8b62d896e3fb228c7af656a684834f4970"}, "earmark": {:hex, :earmark, "1.3.1", "73812f447f7a42358d3ba79283cfa3075a7580a3a2ed457616d6517ac3738cb9", [:mix], [], "hexpm", "000aaeff08919e95e7aea13e4af7b2b9734577b3e6a7c50ee31ee88cab6ec4fb"}, - "earmark_parser": {:hex, :earmark_parser, "1.4.17", "6f3c7e94170377ba45241d394389e800fb15adc5de51d0a3cd52ae766aafd63f", [:mix], [], "hexpm", "f93ac89c9feca61c165b264b5837bf82344d13bebc634cd575cb711e2e342023"}, - "ex_doc": {:hex, :ex_doc, "0.25.5", "ac3c5425a80b4b7c4dfecdf51fa9c23a44877124dd8ca34ee45ff608b1c6deb9", [: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", "688cfa538cdc146bc4291607764a7f1fcfa4cce8009ecd62de03b27197528350"}, + "earmark_parser": {:hex, :earmark_parser, "1.4.18", "e1b2be73eb08a49fb032a0208bf647380682374a725dfb5b9e510def8397f6f2", [:mix], [], "hexpm", "114a0e85ec3cf9e04b811009e73c206394ffecfcc313e0b346de0d557774ee97"}, + "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"}, "excoveralls": {:hex, :excoveralls, "0.7.2", "f69ede8c122ccd3b60afc775348a53fc8c39fe4278aee2f538f0d81cc5e7ff3a", [:mix], [{:exjsx, ">= 3.0.0", [hex: :exjsx, repo: "hexpm", optional: false]}, {:hackney, ">= 0.12.0", [hex: :hackney, repo: "hexpm", optional: false]}], "hexpm", "ef8fc1c6014b16a68dccfba3513aa41283d731eeaf8a1b704bbb072cb1ab89cb"}, "exjsx": {:hex, :exjsx, "4.0.0", "60548841e0212df401e38e63c0078ec57b33e7ea49b032c796ccad8cde794b5c", [:mix], [{:jsx, "~> 2.8.0", [hex: :jsx, repo: "hexpm", optional: false]}], "hexpm", "32e95820a97cffea67830e91514a2ad53b888850442d6d395f53a1ac60c82e07"}, "geo": {:hex, :geo, "3.0.0", "bb1e9baac6031c5bbddcde4937af1c1ab1cbfbbe2f7870038fdfc93a9cad4359", [:mix], [], "hexpm", "40a1acc0c8c437d548b5c58505de2800ab6c0fb40950b1e39b6f21dd08e5ba0d"}, diff --git a/test/envelope_test.exs b/test/envelope_test.exs old mode 100755 new mode 100644 diff --git a/test/test_helper.exs b/test/test_helper.exs old mode 100755 new mode 100644